@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-review/references/agents/agents-lowcode-rules.md

@@ -1,79 +1,71 @@
 # Agents — Low-code Judgment Rule Catalog
 
-Judgment rules for **low-code** agents (`agent.json`). Each rule requires the agent to read source and reason — what a regex/count/schema-walk cannot decide reliably. Same row schema as elsewhere — see [`../rule-format.md`](../rule-format.md).
+Judgment rules for **low-code** agents (`agent.json`). Each rule requires reading source and reasoning; regex/count/schema-walk checks are insufficient. Use the row schema in [`../rule-format.md`](../rule-format.md).
 
-> **This catalog is judgment-only.** Run `uip agent review "<PROJECT_DIR>" --output json` **first** (SKILL.md Step 2.5) — it returns the deterministic low-code findings (structural gates, schema-property presence, placeholder cross-refs, eval-set structure and schema cross-refs, guardrail configuration validity) in the same rule format. Then apply the rules below, which the CLI cannot do.
+> **Judgment-only catalog.** Run `uip agent review "<PROJECT_DIR>" --output json` **first** (SKILL.md Step 2.5). It returns deterministic low-code findings—structural gates, schema-property presence, placeholder cross-refs, eval-set structure and schema cross-refs, and guardrail configuration validity—in the same rule format. Then apply these rules.
 
 Read [`../rule-format.md`](../rule-format.md) and [`../rule-catalog-workflow.md`](../rule-catalog-workflow.md) first.
 
 ## Layouts
 
-Low-code agents exist in two layouts. Detect first, then apply the right `Read` path in each rule.
+Detect the layout before reading each rule's sources.
 
 | Layout | Identifier | Key files |
 |---|---|---|
-| **Normalized** | A single JSON file with snake_case top-level keys (`system_prompt`, `tools`, `datasets`, `input_schema`, `output_schema`, `user_prompt`) | The single JSON file |
-| **Agent-builder** | `agent.json` at project root with camelCase keys + sibling `project.uiproj` and `resources/<Name>/resource.json` | `agent.json`, `resources/*/resource.json`, `evals/eval-sets/*.json`, `evals/evaluators/*.json` |
+| **Normalized** | One JSON file with snake_case top-level keys (`system_prompt`, `tools`, `datasets`, `input_schema`, `output_schema`, `user_prompt`) | The single JSON file |
+| **Agent-builder** | Root `agent.json` with camelCase keys, sibling `project.uiproj`, and `resources/<Name>/resource.json` | `agent.json`, `resources/*/resource.json`, `evals/eval-sets/*.json`, `evals/evaluators/*.json` |
 
-Rules tagged `(agent-builder only)` skip silently on the normalized layout; `(normalized only)` skip on agent-builder. Untagged rules apply to both with layout-aware `detection_method`.
+Rules tagged `(agent-builder only)` skip silently on normalized layout; `(normalized only)` skip on agent-builder. Untagged rules apply to both with layout-aware `detection_method`.
 
-## How to read this file
+## How to apply rules
 
-One H2 section per checker class (`EvalsChecker`, `SchemaChecker`, `ToolsChecker`, `GuardrailsChecker`, `GeneralChecker`) groups related rules for navigation. Every row's `detection_method` is the **judgment form**: read the named source, reason about it, emit when the criteria hold. Log the reasoning in the finding's `description`.
-
----
+Sections group checker classes: `EvalsChecker`, `SchemaChecker`, `ToolsChecker`, `GuardrailsChecker`, and `GeneralChecker`. Every `detection_method` is a judgment instruction: read the named source, reason, emit only when criteria hold, and record the reasoning in the finding's `description`.
 
 ## EvalsChecker
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `LC_EVAL_INPUT_DIVERSITY` | warning | evals | Eval datapoints do not span the scenario classes the agent will meet in production | Read `evals/eval-sets/*.json` datapoints plus the agent's purpose, `inputSchema`, tools, and escalations. Assess semantically — not by count — whether the set spans distinct classes: happy path, edge/boundary values, malformed or missing input, ambiguous or unresolvable requests, and every declared side effect (each tool and escalation path). Emit when whole classes are absent or when the datapoints are paraphrases of one scenario. Name the missing classes in the description; do not assert a target datapoint count. file = eval set JSON. | Author datapoints for the missing scenario classes, covering each declared tool and escalation path. |
-| `LC_EVAL_GROUND_TRUTH_SWAPPED` | warning | evals | ≥2 eval datapoints share substantially overlapping input shape but disagree on `expectedOutput` (suggests label swap) | Read `evals/eval-sets/*.json`. For each pair of datapoints, compare `inputs` content overlap (e.g., `email_subject` + `email_body` substring overlap > 80%). Assess: when inputs are near-identical but expected outputs differ, this is a likely label swap (the *opposite* failure pattern from the deterministic duplicate-output check). Emit one finding per swapped pair, element = `<id_1>,<id_2>`. file = eval set JSON. | Inspect both datapoints; correct the swapped label, or split them into clearly distinct scenarios. |
-| `LC_EVAL_JUDGE_FOR_CLOSED_CLASS` | warning | evals | LLM-judge evaluator applied to a closed-class output field | Read eval set's `evaluatorRefs`. Read agent's `outputSchema.properties`. Assess: if any output property has `.enum` (closed set) AND an evaluator referenced by the eval set is an LLM-judge (`evaluatorTypeId: "uipath-llm-judge-output-semantic-similarity"` or similar), the LLM judge is the wrong tool — `uipath-multiclass-classification` / `uipath-exact-match` gives 100% of the signal at zero variance. Emit one finding per (eval-set, judge-evaluator) pair. file = eval set JSON. | Replace the LLM-judge with `uipath-multiclass-classification` or `uipath-exact-match` for closed-class outputs. |
-| `LC_EVAL_ARCHETYPE_FIT` | warning | evals | Evaluator mix does not measure the agent behavior or failure risk that matters | Read the agent purpose, tools, output schema, eval scenarios, and referenced evaluator configurations. Assess whether the evaluators measure the primary contract: exact or multiclass comparison for closed outputs, structural comparison for structured integration results, trajectory or tool behavior when path and side effects matter, and rubric-based judgment for genuinely subjective generation. Emit the most specific mismatch and skip a closed-class mismatch already covered by `LC_EVAL_JUDGE_FOR_CLOSED_CLASS`. file = eval set JSON. | Replace or supplement the evaluator mix so it measures the agent's primary output contract, decision path, and highest-risk failure modes. |
-| `LC_EVAL_JUDGE_RUBRIC_FIT` | warning | evals | LLM-judge instructions are too vague to produce a stable, auditable assessment | Read each LLM-judge evaluator's prompt, criteria, score or label contract, and target output. Emit when a subjective judgment has no explicit criteria, evidence expectations, or distinction between score levels, or when the rubric does not match the behavior under evaluation. Do not require hidden chain-of-thought or a particular model. file = evaluator JSON, element = evaluator name. | Define observable criteria and score or label boundaries, and require a concise evidence-based justification appropriate for audit. |
-| `LC_EVAL_MOCK_CONTRACT_DRIFT` | warning | evals | Eval-set mock response contradicts the mocked tool's declared output contract | Read the mock definitions in `evals/eval-sets/*.json` and each mocked tool's `outputSchema` (normalized: `.tools[]`; agent-builder: `resources/<Name>/resource.json`). Assess per mock: do the payload's property names, types, required fields, and enum members match what the tool declares it returns? Emit when the mock returns a shape the tool cannot produce — evaluations then pass against a contract production never emits. Tools with no declared output schema have nothing to compare; skip those mocks. file = eval set JSON, element = `<tool_name>`. | Update the mock payload to the tool's declared output shape, or correct the tool's `outputSchema` when the mock reflects what the tool really returns. |
-| `LC_EVAL_AGENT_DEFINITION_DRIFT` | warning | evals | Eval datapoint expects a resource, tool, or behavior the agent definition does not provide | Read what the datapoints expect — expected behavior, expected output, simulation instructions — against the agent definition, tools, and resources. Assess per datapoint: does the agent, as configured, have every index, resource, tool, and escalation the expectation names — and does the expectation stay inside what the definition instructs? Emit when the expectation is unsatisfiable by the agent as configured, so the datapoint scores against a definition that does not exist. A paraphrase of a bound resource is not drift; a name the agent binds nowhere is. file = eval set JSON, element = datapoint id. | Point the expectation at the resource, tool, or behavior the agent declares, or bind the missing element to the agent. |
-
----
+| `LC_EVAL_INPUT_DIVERSITY` | warning | evals | Eval datapoints omit production scenario classes | Read `evals/eval-sets/*.json`, agent purpose, `inputSchema`, tools, and escalations. Semantically assess coverage of happy path, edge/boundary values, malformed or missing input, ambiguous/unresolvable requests, every declared side effect (each tool), and every escalation path. Emit when a whole class is absent or datapoints are paraphrases; name missing classes and do not assert a target count. file = eval set JSON. | Add datapoints for missing classes, each declared tool, and each escalation path. |
+| `LC_EVAL_GROUND_TRUTH_SWAPPED` | warning | evals | Near-identical inputs have different `expectedOutput` values | Read `evals/eval-sets/*.json`; compare datapoint pairs for substantially overlapping `inputs` content, such as `email_subject` + `email_body` substring overlap > 80%. Emit one finding per likely swapped pair—the opposite pattern from deterministic duplicate-output checking—element = `<id_1>,<id_2>`. file = eval set JSON. | Inspect both datapoints; correct the label or split the scenarios clearly. |
+| `LC_EVAL_JUDGE_FOR_CLOSED_CLASS` | warning | evals | An LLM judge evaluates a closed-class output field | Read eval `evaluatorRefs` and `outputSchema.properties`. If any output property has `.enum` and a referenced evaluator is an LLM judge (`evaluatorTypeId: "uipath-llm-judge-output-semantic-similarity"` or similar), emit one finding per `(eval-set, judge-evaluator)` pair. `uipath-multiclass-classification` / `uipath-exact-match` provides the relevant signal without judge variance. file = eval set JSON. | Replace the judge with `uipath-multiclass-classification` or `uipath-exact-match`. |
+| `LC_EVAL_ARCHETYPE_FIT` | warning | evals | Evaluators do not measure the agent's contract or main failure risks | Read purpose, tools, output schema, scenarios, and evaluator configurations. Assess whether evaluators cover exact/multiclass comparison for closed outputs, structural comparison for structured integration results, trajectory/tool behavior when path or side effects matter, and rubric judgment for genuinely subjective generation. Emit the most specific mismatch; skip a closed-class mismatch already covered by `LC_EVAL_JUDGE_FOR_CLOSED_CLASS`. file = eval set JSON. | Replace or supplement evaluators for the primary contract, decision path, and highest-risk failures. |
+| `LC_EVAL_JUDGE_RUBRIC_FIT` | warning | evals | LLM-judge instructions are vague or mismatched | Read each LLM-judge prompt, criteria, score/label contract, and target output. Emit when subjective assessment lacks explicit criteria, evidence expectations, score-level distinctions, or a matching rubric. Do not require hidden chain-of-thought or a particular model. file = evaluator JSON, element = evaluator name. | Define observable criteria, score/label boundaries, and a concise evidence-based justification for audit. |
+| `LC_EVAL_MOCK_CONTRACT_DRIFT` | warning | evals | A mock response contradicts the mocked tool's output contract | Read mocks in `evals/eval-sets/*.json` and each mocked tool's `outputSchema` (normalized: `.tools[]`; agent-builder: `resources/<Name>/resource.json`). Compare property names, types, required fields, and enum members. Emit per mismatching mock; skip tools without declared output schemas. file = eval set JSON, element = `<tool_name>`. | Align the mock with the declared schema, or correct the schema if the mock is authoritative. |
+| `LC_EVAL_AGENT_DEFINITION_DRIFT` | warning | evals | An eval expects an unavailable resource, tool, or behavior | Read each datapoint's expected behavior, expected output, and simulation instructions against the definition, tools, and resources. Emit per datapoint when it names an index, resource, tool, escalation, or behavior the configured agent cannot provide. A paraphrase of a bound resource is not drift; a name bound nowhere is. file = eval set JSON, element = datapoint id. | Point the expectation at a declared element or bind the missing element. |
 
 ## SchemaChecker
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `SCHEMA_NO_DESCRIPTIONS` | judgment | schema | Input/output schema properties lack **informative** descriptions | Read `.input_schema` / `.output_schema` in normalized JSON, or `agent.json.inputSchema` / `outputSchema` in Agent Builder. Judge property descriptions for useful semantic guidance, not mere presence; assess input and output separately. | Add a useful description to each property. |
-| `LC_OUTPUT_FORMAT_PROMPT_DRIFT` | warning | schema | System prompt instructs an output shape that conflicts with `outputSchema` | Read system prompt + `outputSchema`. Assess: does the prompt instruct a shape (`"respond with a single sentence"`, `"answer in markdown"`) that conflicts with the schema's structure (structured JSON, flat string, etc.)? Emit when prompt-vs-schema drift is present. file = system prompt source. | Align the prompt's output-format instructions with `outputSchema` — pick one source of truth and have the other reference it. |
-| `LC_INPUT_SCHEMA_OVERLAP` | warning | schema | Input schema has ≥2 fields with semantically overlapping names or descriptions | Read `inputSchema.properties`. Assess: are there fields with semantically overlapping names (`query` vs `question` vs `text` vs `prompt` vs `input`) or descriptions? Emit when ≥2 fields could reasonably hold the same content and the LLM would have to disambiguate at runtime. file = schema source, element = `<field_a>,<field_b>`. | Merge overlapping fields, or differentiate them with clear names + descriptions that scope each one. |
-| `LC_OUTPUT_ENUM_VS_PROMPT_DRIFT` | warning | schema | Output enum disagrees with the prompt's category list (either side has extras) | Read `outputSchema.properties.<X>.enum` and the system prompt's classification list (`"Classify into: A, B, C"`). Assess: do the two sets agree? Emit when either has extras: prompt names a class the schema doesn't accept (runtime validation rejects), OR schema accepts a class the prompt never mentions (LLM never produces it). file = schema or prompt source. | Reconcile the prompt's class list with `outputSchema.enum`. |
-| `LC_OUTPUT_CLASSIFIER_NO_ENUM` | warning | schema | Classifier-shaped agent has no `enum` constraint on the primary output field | Read `outputSchema`. Assess: is this a classifier? Heuristic — `outputSchema` has a single primary string field whose name matches `class` / `classification` / `label` / `category` / `intent` / `decision`, OR the system prompt enumerates fewer than 10 categories. Emit when that field has no `enum`. file = schema source, element = field name. | Add `"enum": [...]` to the field — without it, the LLM produces free-form strings the runtime can't disambiguate. |
-| `LC_OUTPUT_DECISION_NO_RATIONALE` | info | schema | Output schema carries a consequential decision with no field recording why | Read `outputSchema` and the agent's purpose. Assess: does every property hold a terminal value a consumer acts on (enum label, boolean, identifier, score), with none carrying rationale, evidence, or citation? Emit only when the decision is consequential — classification, approval, routing, eligibility; a passthrough or formatting agent does not qualify. Without a rationale field a wrong decision leaves no trace of what the model weighed. file = schema source. | Add a `reasoning` / `justification` / `citations` property and instruct the prompt to populate it. |
-| `LC_OUTPUT_CONSUMER_DRIFT` | warning | schema | A project in review scope consumes the agent's result but reads fields, types, or states `outputSchema` does not declare | Applies only when the Step 1 project table lists a consumer of this agent (sibling flow, RPA project, API workflow, or agent invoking it). Read how the consumer uses the agent result and read `outputSchema`. Assess: does the consumer read a property the schema omits, assume a different type, or branch on a status or failure value the schema cannot produce? Emit per concrete mismatch. When no consumer is in review scope the subject set is empty — an out-of-scope caller is not evidence, and an empty subject set is not a skipped rule. file = consumer source, element = `<property>`. | Reconcile the two — add the property to `outputSchema`, or read the property the agent actually declares. |
-
----
+| `SCHEMA_NO_DESCRIPTIONS` | judgment | schema | Input/output properties lack informative descriptions | Read `.input_schema` / `.output_schema` in normalized JSON or `agent.json.inputSchema` / `outputSchema` in Agent Builder. Judge useful semantic guidance, not mere presence; assess input and output separately. | Add a useful description to every property. |
+| `LC_OUTPUT_FORMAT_PROMPT_DRIFT` | warning | schema | System prompt output instructions conflict with `outputSchema` | Read system prompt and `outputSchema`; compare instructed shape—such as `respond with a single sentence` or `answer in markdown`—with structured JSON or flat-string schema. file = system prompt source. | Align prompt and schema, choosing one source of truth. |
+| `LC_INPUT_SCHEMA_OVERLAP` | warning | schema | At least two input fields could hold the same content | Read `inputSchema.properties`; assess overlapping names/descriptions such as `query`, `question`, `text`, `prompt`, and `input`. Emit when the LLM must disambiguate at runtime. file = schema source, element = `<field_a>,<field_b>`. | Merge fields or differentiate names and descriptions. |
+| `LC_OUTPUT_ENUM_VS_PROMPT_DRIFT` | warning | schema | Output enum disagrees with the prompt's category list | Read `outputSchema.properties.<X>.enum` and prompt classification lists such as `Classify into: A, B, C`. Emit if either side has extras: runtime rejects prompt-only classes, while schema-only classes are not prompted. file = schema or prompt source. | Reconcile the prompt list and `outputSchema.enum`. |
+| `LC_OUTPUT_CLASSIFIER_NO_ENUM` | warning | schema | Classifier-shaped primary output has no `enum` | Read `outputSchema`. Treat it as classifier-shaped when it has one primary string field named like `class`, `classification`, `label`, `category`, `intent`, or `decision`, or when the prompt enumerates fewer than 10 categories. Emit if that field lacks `enum`. file = schema source, element = field name. | Add `"enum": [...]` to the field. |
+| `LC_OUTPUT_DECISION_NO_RATIONALE` | info | schema | Consequential decision output records no rationale | Read `outputSchema` and purpose. Emit only for consequential classification, approval, routing, or eligibility decisions whose properties are terminal values—enum, boolean, identifier, or score—with no rationale, evidence, or citation. Do not flag passthrough or formatting agents. file = schema source. | Add a `reasoning` / `justification` / `citations` property and prompt for it. |
+| `LC_OUTPUT_CONSUMER_DRIFT` | warning | schema | An in-scope consumer reads undeclared fields, types, or states | Apply only when Step 1 lists a consumer such as a sibling flow, RPA project, API workflow, or invoking agent. Read consumer use and `outputSchema`; emit per concrete omitted property, type mismatch, or impossible status/failure branch. With no in-scope consumer, the subject set is empty; an out-of-scope caller is not evidence, and an empty subject set is not a skipped rule. file = consumer source, element = `<property>`. | Add the property/state to `outputSchema` or read what the agent declares. |
 
 ## ToolsChecker
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `VAGUE_TOOL_DESCRIPTION` | judgment | tools | Tool description missing or too vague for the LLM to choose the tool correctly | Walk tools (normalized: `.tools[]`; agent-builder: each `resources/*/resource.json` with `.type == "tool"`). Read each `.description`. Assess: does it state purpose, side effects, and when to use vs not use — enough that the model can pick this tool over its siblings? A blank description, or boilerplate like `"Process invoice"` that names no effect or selection cue, fires; a 2-3 sentence description covering purpose + effects + usage does not. (The crude `<20-char` length check runs in the review CLI; this rule judges sufficiency.) file = tool source, element = tool name. | Write a 2-3 sentence description covering purpose, side effects, and when to use vs not use the tool. |
-| `LC_TOOL_MINIMALITY_SUFFICIENCY` | warning | tools | Tools exist that the prompt never names, OR the prompt describes responsibilities with no tool to fulfill them | Read tool list + system prompt. Assess two directions: (a) every configured tool maps to a clearly stated responsibility in the prompt; (b) every prompt-stated responsibility has at least one tool to fulfill it. Emit one finding per gap, with `description` naming the unmapped tool or unmet responsibility. file = system prompt source. | Either add the responsibility to the prompt (for orphan tools), add a tool (for orphan responsibilities), or remove the unused tool. |
-| `LC_TOOL_OVERLAP` | warning | tools | Two or more tools have substantially similar descriptions or overlapping input schemas | Read all tool descriptions + `inputSchema`s. Assess pairwise: do any two tools have descriptions a user could plausibly apply to the same request, or input schemas that look interchangeable? Emit one finding per overlapping pair, element = `<tool_a>,<tool_b>`. file = tool source. | Differentiate the tools — sharpen descriptions to make selection unambiguous, or merge if truly redundant. |
-| `LC_TOOL_DANGEROUS_COMBINATION` | warning | tools | Tool combination creates risk no individual tool creates alone (e.g., read tool + write tool with no guardrail) | Read full tool list. Assess pairwise / N-wise: do any combinations create capabilities none of the individual tools has alone? Classic example: a read tool (search, retrieve, query) + a write tool (send email, create record, call API) with no output guardrail = data-exfiltration path. Emit per dangerous combination. file = tool source, element = `<tool_a>,<tool_b>`. | Add a guardrail (e.g., output `pii_detection`, scope-restriction policy) that breaks the dangerous flow, or remove one tool. |
-| `LC_TOOL_DELEGATION_DEPTH` | warning | tools | Tool with `type: "agent"` has no prompt guidance on when to delegate vs handle directly | Read tool resources. Identify any with `.type == "agent"`. Read system prompt. Assess: does the prompt include delegation criteria? Emit when missing. file = tool source, element = tool name. | Add delegation criteria to the system prompt: when to call the sub-agent vs handle the query directly. |
-| `LC_TOOL_DESCRIPTION_MISLEADING` | info | tools | Tool description contradicts its declared `inputSchema` or `outputSchema` | For each tool, read `.description`, `.inputSchema`, `.outputSchema`. Assess: does the description claim behavior that contradicts the schemas (e.g., "returns the customer's full name" but `outputSchema` is `{type: "boolean"}`, or "takes a customer ID and email" but `inputSchema.properties` lists only `id`)? Emit per clear semantic mismatch (return type, field set, or arg count). file = tool source, element = tool name. | Reconcile the description with the actual schemas — pick the source of truth and update the other. |
-| `LC_TOOL_PURPOSE_AUTHORITY_FIT` | warning | tools | A configured tool grants materially more authority than the agent's business purpose requires | Read the system prompt, business context, and complete tool set. Compare each tool's side effects and effective authority with the decisions the agent is intended to make. Emit when a read-only or advisory use case receives unnecessary create, update, delete, send, admin, or cross-system capability, even if the prompt mentions the tool. file = tool source, element = tool name. | Remove the tool, replace it with a narrower read-only operation, or constrain the capability to the minimum action and scope the business purpose requires. |
-| `LC_PROMPT_REFERENCES_NONEXISTENT_RESOURCE` | warning | tools | Prompt appears to direct the agent to a tool, context source, or escalation resource that is not configured | Read the prompt and configured resource names and descriptions. Use semantic matching rather than exact token comparison: distinguish ordinary business nouns from instructions that clearly refer to an executable or grounded resource. Emit only when the prompt relies on a resource with no plausible configured match; name the unsupported instruction. file = system prompt source. | Configure the referenced resource, rewrite the instruction to name the actual resource, or remove the unsupported instruction. |
-| `LC_MULTI_TOOL_NO_SEQUENCING` | warning | tools | Tools with implicit ordering exist together but the prompt establishes no order | Read tool list. Identify canonical ordered pairs: `search*` + `summarize*`; `get*` + `create*`; `validate` + `submit`. Read system prompt. Assess: does the prompt establish ordering with words like `first`, `then`, `after`, or numbered steps? Emit when tools-with-implicit-order exist together but no ordering language appears. file = system prompt source. | Add numbered steps or sequencing language to the system prompt. |
-| `LC_UNGROUNDED_DOMAIN_KNOWLEDGE` | warning | tools | Prompt relies on organization-specific knowledge the agent has no way to retrieve | Read the system prompt for assertions or procedures that depend on organization-specific facts (internal policy, product catalog, approval thresholds, team ownership) rather than general knowledge. Read the configured context resources and tools. Emit when nothing can supply that knowledge — the model then answers from parametric memory and hallucinates plausibly. `LC_TOOL_RESPONSE_NOT_GROUNDED` covers retrieval that exists without a grounding instruction; this covers retrieval that is absent entirely. Do not flag prompts that state their domain facts inline. file = system prompt source. | Configure a context source or retrieval tool for the referenced knowledge, or state the required facts inline in the prompt. |
-| `LC_CONTEXT_SOURCE_OVERLAP` | warning | tools | Two or more context sources are described in terms that give retrieval no cue for choosing between them | Read every context resource (`$resourceType: "context"`) `description` and `query.description`, plus the index each points at. Assess pairwise: does each description name the corpus it covers and the question types it answers, so one source is selectable over the other? Emit per overlapping pair when both descriptions apply equally to the same request. Single-source agents have an empty subject set. The review CLI's `LOWCODE_CONTEXT_NO_DESCRIPTION` owns presence; this rule judges distinctness. file = context resource, element = `<source_a>,<source_b>`. | Rewrite each description to name its corpus and the question types it answers, so multi-source retrieval has an unambiguous selection cue. |
-| `LC_CONTEXT_RETRIEVAL_SETTINGS_FIT` | judgment | tools | Retrieval `threshold` / `resultCount` unfit for the corpus and answer contract | Read `settings.threshold` / `resultCount`, the corpus, and the prompt's answer contract. `threshold: 0` is the default, accepting every match regardless of score; raising it improves precision but risks dropping relevant passages — neither extreme is a defect alone. Assess against representative positive, ambiguous, and no-answer queries: can a query with nothing relevant still return a full `resultCount` of chunks, and does the prompt have a path to say so? Weigh recall against latency and token cost. Name the failing query class; assert no target number. file = context resource, element = resource name. | Tune `threshold` / `resultCount` against representative positive, ambiguous, and no-answer queries; cover the no-answer case with an eval datapoint. |
-| `LC_TOOL_RESPONSE_NOT_GROUNDED` | warning | tools | Agent has RAG-shaped retrieval but no grounding instruction in prompt or context resource | First confirm RAG shape: a tool whose output is unstructured prose intended to be cited, OR a Context Grounding index resource (`$resourceType: "context"` with `contextType: "index"`). Structured-record tools (`searchOrders`, `lookupCustomer`) do NOT trigger. When RAG-shaped, read system prompt AND every context resource's `description` / `query.description`. Assess: does grounding instruction (`"answer based only on retrieved content"` / `"cite the source"` / `"if no result, say I don't know"`) appear in either location? Emit when missing. file = system prompt or context resource. | Add a grounding instruction either to the system prompt or to the context resource's description. |
-
----
+| `VAGUE_TOOL_DESCRIPTION` | judgment | tools | Tool description is missing or insufficient for selection | Walk normalized `.tools[]` or agent-builder `resources/*/resource.json` where `.type == "tool"`. Read `.description`; require purpose, side effects, and when to use versus siblings. Blank or boilerplate such as `Process invoice` fires; a 2-3 sentence description covering those points does not. file = tool source, element = tool name. | Write a 2-3 sentence description covering purpose, effects, and use/non-use conditions. |
+| `LC_TOOL_MINIMALITY_SUFFICIENCY` | warning | tools | Tools are unnamed by the prompt, or prompt responsibilities lack tools | Read tool list and system prompt. Check both directions: every tool maps to a stated responsibility, and every stated responsibility has a tool. Emit one finding per gap and name it. file = system prompt source. | Add the responsibility, add a tool, or remove the unused tool. |
+| `LC_TOOL_OVERLAP` | warning | tools | Tools have substantially overlapping descriptions or input schemas | Read all descriptions and `inputSchema`s pairwise. Emit when users could plausibly apply two tools to the same request or schemas are interchangeable. element = `<tool_a>,<tool_b>`. file = tool source. | Sharpen selection cues or merge redundant tools. |
+| `LC_TOOL_DANGEROUS_COMBINATION` | warning | tools | Tool combinations create a capability or risk absent from individual tools | Read the full list pairwise/N-wise. Flag combinations such as read/search/retrieve plus write/send/create/API with no output guardrail, creating a data-exfiltration path. file = tool source, element = `<tool_a>,<tool_b>`. | Add a guardrail such as `pii_detection` or scope restriction, or remove one tool. |
+| `LC_TOOL_DELEGATION_DEPTH` | warning | tools | An agent tool lacks delegation criteria | Identify resources with `.type == "agent"`; read the system prompt and emit when it does not say when to delegate versus handle directly. file = tool source, element = tool name. | Add delegation criteria. |
+| `LC_TOOL_DESCRIPTION_MISLEADING` | info | tools | Description contradicts declared input/output schemas | Read each description, `inputSchema`, and `outputSchema`. Emit per clear semantic mismatch in return type, fields, or argument count. file = tool source, element = tool name. | Reconcile description and schemas. |
+| `LC_TOOL_PURPOSE_AUTHORITY_FIT` | warning | tools | Tool authority exceeds the business purpose | Read prompt, business context, and tools. Emit when a read-only/advisory use case has unnecessary create, update, delete, send, admin, or cross-system capability, even if mentioned by the prompt. file = tool source, element = tool name. | Remove, narrow, or constrain the tool to required action and scope. |
+| `LC_PROMPT_REFERENCES_NONEXISTENT_RESOURCE` | warning | tools | Prompt relies on an unconfigured executable or grounded resource | Read prompt and configured names/descriptions; match semantically, distinguishing business nouns from executable or grounded resources. Emit only when no plausible configured match exists; name the unsupported instruction. file = system prompt source. | Configure it, name the actual resource, or remove the instruction. |
+| `LC_MULTI_TOOL_NO_SEQUENCING` | warning | tools | Implicitly ordered tools have no prompt order | Identify canonical pairs such as `search*` + `summarize*`, `get*` + `create*`, and `validate` + `submit`. Read prompt; emit when no `first`, `then`, `after`, or numbered ordering appears. file = system prompt source. | Add ordered steps or sequencing language. |
+| `LC_UNGROUNDED_DOMAIN_KNOWLEDGE` | warning | tools | Prompt depends on organization-specific knowledge unavailable to the agent | Read prompt for internal policy, catalog, thresholds, ownership, or other non-general facts; read context resources and tools. Emit when nothing supplies the knowledge. Do not flag facts stated inline. `LC_TOOL_RESPONSE_NOT_GROUNDED` covers retrieval that exists without grounding; this rule covers absent retrieval. file = system prompt source. | Configure context/retrieval or state the facts inline. |
+| `LC_CONTEXT_SOURCE_OVERLAP` | warning | tools | Context sources provide no retrieval-selection cue | Read every `$resourceType: "context"` resource's `description`, `query.description`, and referenced index. Emit per pair when descriptions do not distinguish corpus and question types. Single-source agents have an empty subject set. `LOWCODE_CONTEXT_NO_DESCRIPTION` owns presence; this rule judges distinctness. file = context resource, element = `<source_a>,<source_b>`. | Describe each corpus and question types clearly. |
+| `LC_CONTEXT_RETRIEVAL_SETTINGS_FIT` | judgment | tools | `threshold` / `resultCount` do not fit corpus and answer contract | Read settings, corpus, prompt contract, and representative positive, ambiguous, and no-answer queries. `threshold: 0` accepts every match regardless of score; higher thresholds improve precision but can drop relevant passages. Assess recall, latency, token cost, whether no-answer queries can still return a full `resultCount`, and whether the prompt can say no answer. Name the failing query class; assert no target number. file = context resource, element = resource name. | Tune `threshold` / `resultCount` with representative queries and add a no-answer eval datapoint. |
+| `LC_TOOL_RESPONSE_NOT_GROUNDED` | warning | tools | RAG-shaped retrieval has no grounding instruction | First confirm RAG shape: unstructured prose intended for citation, or Context Grounding index resource (`$resourceType: "context"` with `contextType: "index"`). Structured-record tools such as `searchOrders` and `lookupCustomer` do not trigger. Read system prompt and every context resource's `description` / `query.description`; emit when no instruction says to answer only from retrieval, cite sources, or say `I don't know` when none is found. file = system prompt or context resource. | Add grounding guidance to the system prompt or context description. |
 
 ## GuardrailsChecker
 
-> **Validator name authority.** Not all validators have the same documentation status. Use only names you are confident the target layout supports:
+> **Validator name authority.** Use only names supported by the target layout.
 >
 > **SDK-documented built-ins** (confirmed by `uipath-python` SDK docs):
 >
@@ -90,64 +82,53 @@ One H2 section per checker class (`EvalsChecker`, `SchemaChecker`, `ToolsChecker
 > | `intellectual_property` | Agent generates code or text | Agent, Llm only | PostExecution only |
 > | `user_prompt_attacks` | User-facing agent, jailbreak risk | Llm only | PreExecution only |
 >
-> When recommending the three "platform-documented" types, do NOT cite them by name unless the specific validator is already present in the project's `guardrails` array or agent-builder schema. Instead say: *"Add an appropriate content-safety guardrail supported by this agent layout."* This applies to `LC_GUARDRAIL_RECOMMENDED` below.
-
-> **Apply these via the structured workflow.** The guardrail rules below are applied through
-> [`guardrails/guardrails-review.md`](guardrails/guardrails-review.md) — Step 0 (fetch the live
-> `uip agent guardrails catalog` + `list`, 30-min cache) → **Audit Mode** (effectiveness/relevance of existing
-> guardrails) + **Recommend Mode** (missing-guardrail recommendations) — modeled on the `uipath-agents` recommend
-> capability and driven by the same live catalog. **Boundary:** the review CLI (Step 2.5a) owns all
-> FORMAT/SCHEMA/SET-MEMBERSHIP checks (`GUARDRAIL_*` / `GUARDRAIL_CUSTOM_*` / `LOWCODE_*GUARDRAIL*`); the rules
-> below fire only on format-valid guardrails and never re-flag a CLI format finding. If the catalog is
-> unavailable, defer the Audit-Mode rows (Rules Skipped) — see the workflow's Step 0.
+> When recommending the three platform-documented types, do not cite them by name unless already present in the project's `guardrails` array or agent-builder schema. Say: *Add an appropriate content-safety guardrail supported by this agent layout.* This applies to `LC_GUARDRAIL_RECOMMENDED`.
+>
+> **Apply these through the structured workflow.** Run [`guardrails/guardrails-review.md`](guardrails/guardrails-review.md) Step 0: fetch the live `uip agent guardrails catalog` + `list` with a 30-min cache. Then run **Audit Mode** for existing guardrails and **Recommend Mode** for missing ones, using the same live catalog and modeling `uipath-agents` recommend capability. The review CLI (Step 2.5a) owns all FORMAT/SCHEMA/SET-MEMBERSHIP checks (`GUARDRAIL_*` / `GUARDRAIL_CUSTOM_*` / `LOWCODE_*GUARDRAIL*`); these rules apply only to format-valid guardrails and never re-flag a CLI format finding. If the catalog is unavailable, defer Audit-Mode rows (Rules Skipped) as specified in Step 0.
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `LC_GUARDRAIL_RECOMMENDED` | info | guardrails | A guardrail is recommended for a use case the agent matches but doesn't cover (one finding per missing guardrail; specifics in the message) | Apply `guardrails/guardrails-review.md` **Recommend Mode**: fetch the live catalog (Step 0); for each catalog entry whose `when_to_use` / `use_cases` / `security_risk_addressed` match the agent (system prompt, schemas, tools) and which is absent from `.guardrails[]`, emit one finding. The message names the guardrail / `security_category`, the matched use case, the recommended scope, and the recommended **action** — **block/escalate** when protection is really needed (PII that must not enter, injection, harmful content) or **log** for audit only (a tool legitimately handles sensitive data). It also preserves a source-evidence clause in the form `<source path>: <exact matching identifier(s)>`; copy schema properties, tool names, and resource names verbatim instead of paraphrasing them (for example, `agent.json inputSchema.properties: customer_email, full_name, ssn`). De-dup by `security_category`. Do NOT name a platform-documented validator unless already present (see note above). file = `agent.json` (or normalized JSON). | Add the named guardrail at the catalog-recommended scope/action (cite `examples[].config`): block/escalate for protection, log for audit. |
-| `LC_GUARDRAIL_ACTION_INEFFECTIVE` | judgment | guardrails | A format-valid guardrail's action is ineffective or counterproductive for its scope | Apply `guardrails/guardrails-review.md` **Audit Mode → Actionability**: for each format-valid guardrail (skip ones the review CLI flagged), compare `validator` + `selector.scopes` + action `$actionType` against the catalog entry's `when_not_to_use` / `examples[].config` action for that scope. Emit when counterproductive — a security-critical guardrail at `log` where the example uses `block`; `pii_detection` `Block`/`Filter` at Tool on a tool that needs the PII; `pii_detection` `Log` at Agent/Llm. Name the recommended action. file = `agent.json`, element = guardrail name. | Set the action the catalog recommends for that scope, or move the guardrail to a scope where the action is effective. |
-| `LC_GUARDRAIL_MISAPPLIED` | judgment | guardrails | A guardrail is present but the agent matches the validator's `when_not_to_use` | Apply `guardrails/guardrails-review.md` **Audit Mode → Relevance**: establish the agent's context (system prompt, schemas, tools); for each format-valid guardrail read the catalog entry's `when_not_to_use` / `NOT_recommended_for`. Emit when the agent matches a disqualifying condition (e.g. a generate-only agent with no user input carrying a PII guardrail). Cite the matched clause. file = `agent.json`, element = guardrail name. | Remove the misapplied guardrail, or document why the agent's context differs from the `when_not_to_use` condition. |
-
----
+| `LC_GUARDRAIL_RECOMMENDED` | info | guardrails | A matching catalog guardrail is absent | Apply `guardrails/guardrails-review.md` **Recommend Mode**. For each catalog entry whose `when_to_use` / `use_cases` / `security_risk_addressed` matches prompt, schemas, or tools and is absent from `.guardrails[]`, emit one finding. Name guardrail / `security_category`, matched use case, recommended scope and **action**: **block/escalate** when protection is needed (PII that must not enter, injection, harmful content), or **log** for audit-only handling. Include source evidence as `<source path>: <exact matching identifier(s)>`; copy schema properties, tool names, and resource names verbatim, e.g. `agent.json inputSchema.properties: customer_email, full_name, ssn`. De-dup by `security_category`; do not name platform-documented validators unless already present. file = `agent.json` (or normalized JSON). | Add the named guardrail at catalog-recommended scope/action, citing `examples[].config`: block/escalate for protection, log for audit. |
+| `LC_GUARDRAIL_ACTION_INEFFECTIVE` | judgment | guardrails | A valid guardrail's action is ineffective or counterproductive | Apply **Audit Mode → Actionability**. For each format-valid guardrail, compare `validator`, `selector.scopes`, and `$actionType` with catalog `when_not_to_use` / `examples[].config` for that scope. Flag security-critical `log` where example uses `block`, `pii_detection` `Block`/`Filter` at Tool when the tool needs PII, and `pii_detection` `Log` at Agent/Llm. Name recommended action. file = `agent.json`, element = guardrail name. | Use the catalog action or move the guardrail to an effective scope. |
+| `LC_GUARDRAIL_MISAPPLIED` | judgment | guardrails | A valid guardrail matches its validator's `when_not_to_use` | Apply **Audit Mode → Relevance**. Read catalog `when_not_to_use` / `NOT_recommended_for`; emit when agent context matches a disqualifying condition, such as a generate-only agent with no user input carrying PII guardrails. Cite the matched clause. file = `agent.json`, element = guardrail name. | Remove it or document why the agent differs from the condition. |
 
 ## GeneralChecker
 
-Covers system-prompt quality, settings fit, no-flow failure modes, and prompt-vs-schema concerns that need reasoning.
+Covers prompt quality, settings fit, failure modes, and prompt/schema reasoning.
 
 | rule_id | severity | category | trigger | detection_method | suggested_fix |
 |---|---|---|---|---|---|
-| `LC_PROMPT_ROLE_DEFINITION` | warning | general | System prompt does not open with a clear role / persona statement | Read system prompt. Assess: does the opening paragraph state what the agent is and what it does? Emit when missing. file = system prompt source. | Add an opening sentence: `"You are an X that does Y."` |
-| `LC_PROMPT_WHEN_GUIDANCE` | warning | general | Prompt explains tool capabilities but not when to use each tool | Read prompt + tool list. Assess per tool: does the prompt explain *when* to use it, not just *what* it does? `"Use SearchKB when the user asks a factual question about company policy"` is good; `"SearchKB: searches the knowledge base"` is not. Emit per tool lacking WHEN guidance. file = system prompt source, element = tool name. | For each tool, add a "use this when …" sentence to the prompt. |
-| `LC_PROMPT_SCOPE_BOUNDARIES` | warning | general | Prompt does not explicitly state what the agent should NOT do | Read system prompt. Assess: does it contain explicit boundaries (`"Do not …"`, `"Only handle questions about X"`, `"If unsure, escalate"`)? Emit when absent. file = system prompt source. | Add a "Scope & Boundaries" section listing what is in and out of scope. |
-| `LC_PROMPT_OUTPUT_FORMAT` | warning | general | `outputSchema` is structured but prompt has no output-format instruction | Read `outputSchema`. Read system prompt. Assess: if the schema has specific named fields (not just a string), does the prompt instruct the agent how to populate them? Emit when missing. file = system prompt source. | Add an "Output Format" section showing the expected structure (or a sample). |
-| `LC_PROMPT_INSTRUCTION_CONFLICTS` | warning | general | Prompt contains internally contradictory instructions | Read system prompt. Assess: are there contradictions (`"Always respond in JSON"` alongside `"Write your response as a friendly paragraph"`)? Emit per contradiction. file = system prompt source. | Pick one instruction; remove or reconcile the other. |
-| `LC_PROMPT_OVERSPECIFICATION` | info | general | Prompt is so specific about exact phrases that it will break on reasonable paraphrase | Read system prompt. Assess: does it handle dozens of exact phrases that paraphrase trivially? A 3-page prompt with 47 explicit phrases is brittle. file = system prompt source. | Generalize the prompt — describe categories of input rather than enumerating phrases. |
-| `LC_PROMPT_STRUCTURE` | info | general | Prompt complexity makes responsibilities, tool guidance, boundaries, or output instructions hard to locate | Read the full prompt in light of its tools, schemas, and decision paths. Emit when multiple distinct concerns are buried in undifferentiated prose or when instruction precedence is unclear; do not use a fixed character or line threshold. A short single-purpose prompt does not need headings. file = system prompt source. | Organize the prompt around the concerns it actually contains, using concise sections, bullets, or ordered steps where they improve instruction precedence and maintenance. |
-| `LC_PROMPT_EXAMPLE_MAINTAINABILITY` | info | general | Inline examples encode deployment cases better retained as evaluations or configuration | Compare prompt examples with the agent's reusable behavior, evaluation scenarios, and deployment-specific data. Emit when examples duplicate test cases, hard-code volatile facts, or require prompt edits whenever a customer case changes. Do not flag examples that clarify a stable output contract or balance ambiguous categories. file = prompt source. | Move volatile cases to evaluation sets or configuration and retain only examples that teach stable, reusable behavior. |
-| `LC_PROMPT_DEPLOYMENT_SPECIFIC_LOGIC` | warning | general | Prompt hard-codes customer, tenant, environment, or policy values expected to vary by deployment | Read the prompt alongside resources, context, schemas, and known deployment model. Emit when names, identifiers, thresholds, recipients, or business rules are presented as universal instructions but should vary across deployments. Do not flag values intentionally fixed by the agent's declared scope. file = prompt source. | Move variable values to configuration or grounded context and keep the prompt focused on stable behavior. |
-| `LC_PROMPT_STOPPING_CRITERIA` | warning | general | Prompt has no explicit stopping criteria for unresolvable cases | Read system prompt. Assess: is there a soft stop (`"If you cannot determine the answer after 3 attempts, respond with what you have"`)? Without one the agent relies entirely on `maxIterations`. Emit when missing. file = system prompt source. | Add an explicit stopping instruction for the "I cannot resolve this" case. |
-| `LC_PROMPT_ESCALATION_CRITERIA` | warning | general | Agent can encounter uncertain or high-risk decisions but the prompt does not say when to escalate | Read the prompt, schemas, tools, escalation resources, and business decision. Identify uncertainty, approval, policy-exception, safety, financial, or destructive-action conditions that should leave the agent's authority. Emit when an escalation path exists without usable trigger criteria, or when the use case clearly needs escalation but defines none. This is distinct from stopping after failed attempts. file = system prompt source. | State concrete escalation conditions and the information the agent must pass to the escalation target; add an escalation resource when the platform flow requires one. |
-| `LC_SETTINGS_MAXITERATIONS_FIT` | judgment | general | `maxIterations` value inconsistent with the agent's stated purpose | Read `.settings.maxIterations` + system prompt. Assess: a simple classifier rarely needs >3-5; a complex multi-tool research agent may need 20-30. Extreme values inconsistent with the agent's purpose are flagged. Emit with reasoning. file = `agent.json` or normalized source. | Adjust `maxIterations` to match the agent's actual loop complexity. |
-| `LC_SETTINGS_TEMPERATURE_FIT` | judgment | general | `temperature` value inappropriate for task | Read `.settings.temperature` + system prompt. Assess: temperature 0 fits deterministic tasks (classification, extraction); non-zero on a classifier produces inconsistent labels. Emit with reasoning. file = `agent.json` or normalized source. | Set temperature to 0 for deterministic tasks; raise to 0.3-0.7 for conversational generation. |
-| `LC_SETTINGS_MAXTOKENS_FIT` | judgment | general | `maxTokens` far exceeds the contracted response, nothing else bounds length | Read `.settings.maxTokens`, `outputSchema`, the prompt's output-format instruction, and eval `expectedOutput` sizes. Assess: does the ceiling match the contracted answer, and does anything else bound generation? Compare using orders of magnitude, and still allow generous overhead. Cite the observed expected-answer size. Do not flag a platform default alone. file = `agent.json` or normalized source. | Lower `maxTokens` to the actual answer size, or bound length in the prompt. |
-| `LC_SETTINGS_MODEL_FIT` | judgment | general | Model unfit for the workload | Read `.settings.model` with purpose, tools, cost and latency. Assess: does capability, cost, or latency match the workload (oversized reasoning model for a lookup; undersized for multi-step orchestration)? Emit with reasoning. Requires a model identifiable from the value itself — a recognizable vendor or platform identifier. Not applicable when the value is a custom or aliased deployment name whose underlying model cannot be determined from the string. file = `agent.json` or normalized source. | Pick a model matching the workload. |
-| `LC_PLACEHOLDER_VALUE` | warning | general | Authored value is a leftover scaffold default or developer placeholder | Read authored values: agent / project `name`, context resource `description` / `query.description`, index and alias names, eval `expectedOutput` and mocks, evaluator prompts. Assess per value: real project content, or unchanged template default (`"Test"`, `"A demo … index"`, `"TODO"`, stock scaffold text, `MyAgent`-style stand-in, typo'd name)? Note that model aliases (BYOM) are not free to change, so don't raise this for model names. file = value's file, element = field path. | Replace placeholder values with real project content. |
-| `LC_FAILURE_HALLUCINATE_ARGS` | warning | general | Tool `inputSchema` has required fields with no descriptions, and the LLM must guess values | Walk tools. For each, read required fields. Assess: are required fields self-explanatory, or do they need descriptions to be filled correctly? Emit when the LLM would have to guess valid values. file = tool source, element = `<tool_name>:<param>`. | Add `description` to each required parameter explaining valid values and format. |
-| `LC_FAILURE_WRONG_TOOL` | warning | general | ≥2 tools have descriptions the LLM could reasonably apply to the same user request | Read all tool descriptions. Assess from a user's perspective: could any two be selected for the same request? Emit per ambiguous pair. file = tool source, element = `<tool_a>,<tool_b>`. | Sharpen descriptions to make tool selection unambiguous. |
-| `LC_FAILURE_PROMPT_INJECTION` | warning | general | Untrusted-content instruction boundary is ineffective OR the system prompt contains jailbreak fragments | Two shapes, fire on either: (a) user, retrieved, or tool-returned content can be reinterpreted as instructions because it is inserted without an effective data boundary or sanitization, and no suitable prompt-injection guardrail is active; literal delimiters are not required when another control is effective. (b) the system prompt attempts to override platform safety, contains DAN-style markers (`"ignore previous"`, `"no restrictions"`, `"do anything now"`), or instructs the model to behave as another assistant (`"As ChatGPT, …"`). file = source of risk. | (a) Treat untrusted content explicitly as data and add sanitization or an appropriate prompt-injection guardrail. (b) Rewrite the system prompt to remove adversarial markers. |
-| `LC_FAILURE_IRREVERSIBLE_ACTION` | warning | general | Tools that create / delete / modify records exist alongside no escalation resource and no prompt confirmation requirement | Walk tools. Identify create/delete/modify capabilities. Read escalation resources + system prompt. Assess: is there an escalation path or prompt instruction to confirm before destructive actions? Emit when absent. file = tool source. | Add an escalation resource gating destructive actions, or add a confirmation requirement to the system prompt. |
-| `LC_FAILURE_AUTHORITY_ESCALATION` | warning | general | Agent has admin-level tools but no prompt restriction on context of use | Walk tools. Identify admin-level capabilities (process invocation, queue manipulation, entity modification). Read system prompt. Assess: does the prompt restrict the context in which these are used? Emit when unrestricted. file = system prompt source. | Restrict admin-level tools in the system prompt to specific user roles / scenarios, or add a guardrail. |
-| `LC_ESCALATION_OVERBROAD` | warning | general | Escalation description uses universal quantifiers without a narrowing condition | Read escalation resource `description`s (and channel `description`s). Assess: does it use universal quantifiers (`"always escalate"`, `"every classification"`, `"all responses"`, `"any output"`, `"regardless of intent"`) near the start AND lack a narrowing condition (`"if confidence < X"`, `"when classification is Uncertain"`, `"only for"`)? Emit when both hold. file = escalation source, element = escalation name. | Add a narrowing condition to the escalation description; if the intent really is to escalate everything, document why. |
-| `LC_PROMPT_FEW_SHOT_MISSING` | warning | general | Structured `outputSchema` (≥3 fields, or ≥2 with nested) but system prompt has no concrete output example | Read `outputSchema` (count fields, check for nested). Read system prompt. Assess: when schema is rich (≥3 fields OR ≥2 with at least one nested), does the prompt include a concrete example (`Example: {…}`, an `Output format:` block with values, in-prompt sample)? 1-2 flat fields don't trigger. Emit when missing. file = system prompt source. | Add a concrete example output to the system prompt — few-shot lifts structured-output accuracy on rich schemas. |
-| `LC_PROMPT_NEGATIVE_HEAVY` | warning | general | >50% of distinct prompt instructions are negative (`do not`, `never`, `avoid`, `must not`, `don't`) | Read system prompt. Tokenize into instructions (sentences, bullets). Assess: what fraction are negative? Emit when >50%. file = system prompt source. | Rewrite negative instructions as positive ones — LLMs follow `"always do X"` more reliably than `"never do not-X"`. |
-| `LC_USER_PROMPT_BIASED_EXAMPLE` | warning | general | User-role message ends with an example output containing a specific concrete class value, unconditioned on input | Read user-role message. Assess (must hold all three): (1) contains `"Example of correct output:"` / `"Example output:"` / `"For example:"` / `"Sample output:"` (or similar header); (2) the example body is JSON-shaped with specific concrete values for classification fields (`"classification": "Accepted"`, `"intent": "approve"`); (3) the template doesn't condition the example on the input (`"for an acceptance email, …"`, `"if the user is asking about billing, …"`). When all three hold, the LLM treats the example's class as the de-facto answer for ambiguous inputs. file = user message source. | Either remove the example, move it to the **system** prompt as one of several balanced examples, or condition it on input shape. |
-
----
+| `LC_PROMPT_ROLE_DEFINITION` | warning | general | Prompt does not open with a clear role/persona | Read prompt; require the opening paragraph to state what the agent is and does. file = system prompt source. | Add an opening sentence such as `You are an X that does Y.` |
+| `LC_PROMPT_WHEN_GUIDANCE` | warning | general | Prompt explains capabilities but not when to use tools | Read prompt and tools; emit per tool lacking a use condition. Capability-only text is insufficient. file = system prompt source, element = tool name. | Add a `use this when …` sentence for each tool. |
+| `LC_PROMPT_SCOPE_BOUNDARIES` | warning | general | Prompt does not state what the agent must not do | Require explicit boundaries such as `Do not …`, `Only handle …`, or `If unsure, escalate`. file = system prompt source. | Add a Scope & Boundaries section. |
+| `LC_PROMPT_OUTPUT_FORMAT` | warning | general | Structured schema has no prompt instructions for populating fields | If `outputSchema` has named fields rather than only a string, read prompt and emit when it does not explain field population. file = system prompt source. | Add an Output Format section with structure or sample. |
+| `LC_PROMPT_INSTRUCTION_CONFLICTS` | warning | general | Prompt contains contradictory instructions | Read the full prompt and emit per contradiction, such as `Always respond in JSON` alongside `Write your response as a friendly paragraph`. file = system prompt source. | Pick one instruction and reconcile/remove the other. |
+| `LC_PROMPT_OVERSPECIFICATION` | info | general | Exact-phrase instructions make paraphrases brittle | Emit when prompt handles many trivial paraphrases individually, such as a 3-page prompt with 47 explicit phrases. file = system prompt source. | Describe input categories instead of enumerating phrases. |
+| `LC_PROMPT_STRUCTURE` | info | general | Prompt complexity hides responsibilities, tools, boundaries, output, or precedence | Read prompt with tools, schemas, and decision paths. Emit when multiple concerns are undifferentiated or precedence is unclear; do not use fixed character/line thresholds, and do not flag a short single-purpose prompt. file = system prompt source. | Use concise sections, bullets, or ordered steps where they improve precedence and maintenance. |
+| `LC_PROMPT_EXAMPLE_MAINTAINABILITY` | info | general | Inline examples encode deployment cases better held in evals/configuration | Compare examples with reusable behavior, eval scenarios, and deployment data. Emit when examples duplicate tests, hard-code volatile facts, or require edits for customer cases. Do not flag stable output-contract examples or balanced ambiguous categories. file = prompt source. | Move volatile cases to eval sets/configuration; retain stable examples. |
+| `LC_PROMPT_DEPLOYMENT_SPECIFIC_LOGIC` | warning | general | Prompt hard-codes values expected to vary by deployment | Read prompt with resources, context, schemas, and deployment model. Flag customer/tenant/environment/policy values, identifiers, thresholds, recipients, or rules presented as universal when variable. Do not flag values fixed by declared scope. file = prompt source. | Move variable values to configuration/grounded context. |
+| `LC_PROMPT_STOPPING_CRITERIA` | warning | general | Prompt lacks a stop for unresolvable cases | Require a soft stop, such as `If you cannot determine the answer after 3 attempts, respond with what you have`; `maxIterations` alone is insufficient. file = system prompt source. | Add explicit unresolved-case stopping instructions. |
+| `LC_PROMPT_ESCALATION_CRITERIA` | warning | general | Uncertainty or high-risk decisions lack usable escalation criteria | Read prompt, schemas, tools, escalations, and business decision. Identify uncertainty, approval, policy-exception, safety, financial, and destructive-action conditions. Emit when an escalation path lacks triggers or the use case clearly needs one but has none. Distinct from stopping after failed attempts. file = system prompt source. | State triggers and handoff information; add an escalation resource when required by the flow. |
+| `LC_SETTINGS_MAXITERATIONS_FIT` | judgment | general | `maxIterations` conflicts with purpose | Read `.settings.maxIterations` and prompt. Simple classifiers rarely need >3-5; complex multi-tool research may need 20-30. Flag extreme values inconsistent with purpose and explain. file = `agent.json` or normalized source. | Adjust to actual loop complexity. |
+| `LC_SETTINGS_TEMPERATURE_FIT` | judgment | general | `temperature` is unfit for the task | Read `.settings.temperature` and prompt. Temperature 0 fits classification/extraction; non-zero classifiers risk inconsistent labels. Explain mismatch. file = `agent.json` or normalized source. | Use 0 for deterministic tasks; 0.3-0.7 for conversational generation. |
+| `LC_SETTINGS_MAXTOKENS_FIT` | judgment | general | `maxTokens` greatly exceeds the contracted response without another bound | Read `.settings.maxTokens`, schema, prompt format, and eval `expectedOutput` sizes. Compare by orders of magnitude with generous overhead; cite observed expected-answer size and do not flag a platform default alone. file = `agent.json` or normalized source. | Lower `maxTokens` or bound length in the prompt. |
+| `LC_SETTINGS_MODEL_FIT` | judgment | general | Model is unfit for workload | Read `.settings.model` with purpose, tools, cost, and latency. Assess capability/cost/latency; flag an oversized model for lookup or undersized model for orchestration. Requires a recognizable vendor/platform identifier; do not apply to custom/aliased deployment names whose model is unknowable from the string. file = `agent.json` or normalized source. | Select a workload-appropriate model. |
+| `LC_PLACEHOLDER_VALUE` | warning | general | Authored value remains scaffold/default placeholder | Read agent/project `name`, context `description` / `query.description`, index and alias names, eval `expectedOutput` and mocks, and evaluator prompts. Flag unchanged defaults such as `Test`, `A demo … index`, `TODO`, stock scaffold text, `MyAgent`-style stand-ins, or typo'd names. Model aliases (BYOM) are not free to change; do not flag them. file = value's file, element = field path. | Replace placeholders with project content. |
+| `LC_FAILURE_HALLUCINATE_ARGS` | warning | general | Required tool fields lack descriptions needed to infer valid values | Walk tools and required fields; emit when fields are not self-explanatory and the LLM must guess values or formats. file = tool source, element = `<tool_name>:<param>`. | Describe valid values and format for every required parameter. |
+| `LC_FAILURE_WRONG_TOOL` | warning | general | At least two descriptions could apply to the same request | Read all descriptions from a user's perspective and emit per ambiguous pair. file = tool source, element = `<tool_a>,<tool_b>`. | Sharpen selection criteria. |
+| `LC_FAILURE_PROMPT_INJECTION` | warning | general | Untrusted instruction boundaries fail or prompt contains jailbreak fragments | Fire on either shape: (a) user/retrieved/tool content can be interpreted as instructions because no effective data boundary/sanitization exists and no suitable prompt-injection guardrail is active; literal delimiters are not required when another control works; or (b) system prompt overrides platform safety, contains DAN-style markers (`ignore previous`, `no restrictions`, `do anything now`), or says to behave as another assistant (`As ChatGPT, …`). file = source of risk. | Treat untrusted content as data and add sanitization or an appropriate prompt-injection guardrail; rewrite adversarial system instructions. |
+| `LC_FAILURE_IRREVERSIBLE_ACTION` | warning | general | Create/delete/modify tools have neither escalation nor confirmation | Walk tools for create/delete/modify capabilities; read escalation resources and prompt. Emit when no escalation path or confirmation requirement exists. file = tool source. | Add escalation gating or require confirmation. |
+| `LC_FAILURE_AUTHORITY_ESCALATION` | warning | general | Admin tools lack contextual restrictions | Walk tools for process invocation, queue manipulation, entity modification, and other admin capabilities; read prompt. Emit when unrestricted. file = system prompt source. | Restrict tools to roles/scenarios or add a guardrail. |
+| `LC_ESCALATION_OVERBROAD` | warning | general | Escalation uses universal quantifiers without narrowing | Read escalation and channel `description`s. Flag `always escalate`, `every classification`, `all responses`, `any output`, or `regardless of intent` near the start when no condition such as `if confidence < X`, `when classification is Uncertain`, or `only for` narrows it. file = escalation source, element = escalation name. | Add a narrowing condition or document why everything must escalate. |
+| `LC_PROMPT_FEW_SHOT_MISSING` | warning | general | Rich structured schema has no concrete prompt output example | If schema has ≥3 fields, or ≥2 with at least one nested, read prompt for `Example: {…}`, an `Output format:` block with values, or another concrete sample. Emit when absent; 1-2 flat fields do not trigger. file = system prompt source. | Add a concrete example output. |
+| `LC_PROMPT_NEGATIVE_HEAVY` | warning | general | More than 50% of distinct instructions are negative | Tokenize sentences/bullets as instructions and count `do not`, `never`, `avoid`, `must not`, and `don't`; emit when >50%. file = system prompt source. | Rewrite negatives positively where possible. |
+| `LC_USER_PROMPT_BIASED_EXAMPLE` | warning | general | User message ends with an unconditional concrete classification example | All must hold: user text has `Example of correct output:`, `Example output:`, `For example:`, `Sample output:`, or similar; example body is JSON-shaped with concrete classification values such as `classification: Accepted` or `intent: approve`; and it is not conditioned on input such as `for an acceptance email` or `if the user is asking about billing`. file = user message source. | Remove it, move it to the system prompt as one of several balanced examples, or condition it on input shape. |
 
 ## What this catalog cannot do
 
-The agent applies these rules from the project source as it is *checked into the repo*. It cannot:
+The agent applies rules to checked-in project source. It cannot:
 
-- Verify the LLM actually follows the prompt at runtime — prompt quality is assessed; LLM compliance can only be confirmed by running the agent.
-- Verify whether tool selection is correct at runtime — overlapping descriptions are flagged as risk; actual selection behavior requires running.
-- Verify whether guardrails fire correctly — structural configuration is checked; whether the underlying service catches a given input is a runtime question.
-- Validate live IDs (connection IDs, index names, recipient addresses) — these require API calls.
+- Verify runtime LLM compliance; run the agent to confirm it.
+- Verify runtime tool selection; overlapping descriptions are risk indicators only.
+- Verify guardrails fire correctly; structural configuration is not service behavior.
+- Validate live IDs such as connection IDs, index names, or recipient addresses; these require API calls.

package/skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md

@@ -167,6 +167,10 @@ the mapping IS needed, fetch via `WebFetch`:
   (`uipath-langchain` in `pyproject.toml` or `from langchain…` / `from langgraph…` imports): middleware classes,
   their supported scopes/stages, and the `uipath_langchain.guardrails` import paths.
 
+The `Platform Availability` notes on these pages are product-wide, so never turn one into a review finding:
+tenant availability comes from `uip agent guardrails list`, and the fetched pages supply class, scope, and
+import names only.
+
 Build a `{ validator_id → { middleware_class, validator_class, entity_enum, allowed_scopes, allowed_stages,
 import_path } }` lookup by joining catalog entries with the SDK class names. Use the fetched content as the sole
 source of truth for class/enum/import names — never memory.