@iris-eval/mcp-server 0.5.0 → 0.6.0

package/dist/tools/deploy-rule.js

@@ -7,16 +7,82 @@
  *
  * Writes to ~/.iris/custom-rules.json (single source of truth) and
  * appends to the audit log. Persisted rules auto-load on server boot
- * and fire on every future evaluate_output call of the matching
- * eval_type.
+ * and fire on every future evaluate_output call whose eval_type equals
+ * the rule's evalType (or eval_type="all").
  */
 import { z } from 'zod';
 import { createCustomRule } from '../eval/rules/custom.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
-import { strictInput } from './strict-input.js';
-const CustomRuleDefinitionSchema = z.object({
-    name: z.string(),
-    type: z.enum([
+import { strictInput, strictNested } from './strict-input.js';
+const EvalTypeSchema = z.enum(['completeness', 'relevance', 'safety', 'cost', 'custom']);
+/**
+ * A rule with this name is already deployed and the caller did not ask to
+ * replace it. Carries the existing rule(s) so an HTTP surface can answer
+ * 409 with them beside the same message the MCP tool throws.
+ */
+export class DuplicateRuleNameError extends Error {
+    existing;
+    constructor(name, existing) {
+        const listed = existing
+            .map((r) => `${r.id} (eval_type ${r.evalType}, severity ${r.severity}, ${r.enabled ? 'enabled' : 'disabled'})`)
+            .join('; ');
+        super(`A rule named "${name}" is already deployed: ${listed}. Deploying a second rule with the same name ` +
+            'would make both fire with indistinguishable rule_results. Pass replace: true to delete the existing rule ' +
+            'and deploy this one in its place, call delete_rule first, or choose a different name. Nothing was deployed.');
+        this.name = 'DuplicateRuleNameError';
+        this.existing = existing;
+    }
+}
+/**
+ * Same-name redeploy (#373). Two rules with one name both fire, and their
+ * rule_results used to be indistinguishable — the same ruleName showing
+ * PASS and FAIL in one response. Refuse by default; with replace:true,
+ * retire the earlier rule(s) first so the name means one thing again. The
+ * store keeps the audit trail either way.
+ *
+ * One function for both deploy surfaces — the `deploy_rule` tool and the
+ * dashboard's `POST /api/v1/rules/custom` — so the semantics and the
+ * wording cannot drift between them. Returns the rules it retired (empty
+ * when the name was free); throws DuplicateRuleNameError when the name is
+ * taken and `replace` is false. Nothing is deployed by this function.
+ */
+export function retireSameNamedRules(store, engine, tenantId, name, replace, user) {
+    const sameName = store.list(tenantId).filter((r) => r.name === name);
+    if (sameName.length === 0)
+        return [];
+    if (!replace)
+        throw new DuplicateRuleNameError(name, sameName);
+    const replaced = [];
+    for (const old of sameName) {
+        if (store.delete(tenantId, old.id, user)) {
+            engine.unregisterRule(old.id);
+            replaced.push({ id: old.id, evalType: old.evalType, severity: old.severity });
+        }
+    }
+    return replaced;
+}
+/** The `warning` both deploy surfaces attach when a replace retired rules. */
+export function replacedRulesWarning(name, replaced) {
+    return (`Replaced ${replaced.length} previously deployed rule(s) named "${name}" ` +
+        `(${replaced.map((r) => r.id).join(', ')}); they no longer fire. Their audit rows are preserved.`);
+}
+/*
+ * Strict one level down, like evaluate_output's custom_rules entries
+ * (#376): a misspelled `wieght` used to be dropped silently. `config`
+ * stays free-form (its keys depend on `type` and are validated by the
+ * store at deploy time). `name` is optional: the server always overwrites
+ * it with the top-level rule name (#377), so requiring a value that is
+ * then discarded only invited a mismatch.
+ */
+const CustomRuleDefinitionSchema = strictNested({
+    name: z
+        .string()
+        .min(1)
+        .max(80)
+        .optional()
+        .describe('Optional and IGNORED if given — the server overwrites it with the top-level `name` so the rule reports under one name everywhere'),
+    type: z
+        .enum([
         'regex_match',
         'regex_no_match',
         'min_length',
@@ -25,55 +91,81 @@ const CustomRuleDefinitionSchema = z.object({
         'excludes_keywords',
         'json_schema',
         'cost_threshold',
-    ]),
-    config: z.record(z.string(), z.unknown()),
-    weight: z.number().optional(),
-});
+    ])
+        .describe('Check type — decides which config keys are required'),
+    config: z
+        .record(z.string(), z.unknown())
+        .describe('Check configuration; required keys depend on type (regex_match: pattern; min_length: min_length; max_length: max_length; contains_keywords/excludes_keywords: keywords; cost_threshold: max_cost; json_schema: none)'),
+    weight: z.number().positive().optional().describe('Weight in the weighted score (default 1; must be > 0)'),
+}, 'definition');
 const inputSchema = {
     // 80 mirrors the persisted store's cap (custom-rule-store.ts). The tool
     // used to allow 120, so a 100-char name passed the tool schema and then
     // surfaced the store's ZodError as a raw 500 (#332). One limit, enforced
     // at the boundary, fails cleanly as a 400.
-    name: z.string().min(1).max(80).describe('Human-readable rule name (1-80 chars; used in eval results)'),
+    name: z.string().min(1).max(80).describe('Human-readable rule name (1-80 chars; used in eval results). Must be unique among deployed rules unless replace=true'),
     description: z
         .string()
         .max(500)
         .optional()
         .describe('What this rule checks for and why it matters'),
-    evalType: z
-        .enum(['completeness', 'relevance', 'safety', 'cost', 'custom'])
-        .describe('Eval category this rule belongs to; determines when it fires'),
+    eval_type: EvalTypeSchema.optional().describe('Eval category this rule belongs to; the rule fires on evaluate_output calls whose eval_type equals it (and on eval_type="all"). Canonical snake_case spelling — pass exactly one of eval_type / evalType'),
+    evalType: EvalTypeSchema.optional().describe('camelCase alias of eval_type, accepted for compatibility — prefer eval_type (snake_case is canonical across the tools)'),
     severity: z
         .enum(['low', 'medium', 'high', 'critical'])
         .default('medium')
         .describe('What a FAILURE of this rule means. low/medium: informational — contributes to the weighted score only (plus dashboard sort + audit alerts). high/critical: hard-fail — a failing evaluation of this rule forces the overall passed=false regardless of the weighted score'),
-    definition: CustomRuleDefinitionSchema.describe('Check definition (regex, length, keyword, cost, or schema)'),
+    definition: CustomRuleDefinitionSchema.describe('Check definition (regex, length, keyword, cost, or schema). Accepts exactly type, config, weight and an optional name — an unknown key is rejected'),
+    source_moment_id: z
+        .string()
+        .optional()
+        .describe('Optional Decision Moment ID the rule was derived from (preserves workflow-inversion provenance). Canonical snake_case — pass exactly one of source_moment_id / sourceMomentId'),
     sourceMomentId: z
         .string()
         .optional()
-        .describe('Optional Decision Moment ID the rule was derived from (preserves workflow-inversion provenance)'),
+        .describe('camelCase alias of source_moment_id, accepted for compatibility — prefer source_moment_id'),
+    replace: z
+        .boolean()
+        .default(false)
+        .describe('When a rule with this name is already deployed: false (default) rejects the call; true deletes the existing same-named rule(s) and deploys this one in their place (fresh id; audit rows preserved)'),
 };
+/*
+ * Exactly one spelling of each aliased argument. Both spellings present
+ * (even with equal values) is refused rather than reconciled — a caller
+ * sending both has a bug somewhere, and silently picking one hides it.
+ */
+const inputSchemaWithAliases = strictInput(inputSchema).superRefine((args, ctx) => {
+    if (args.eval_type === undefined && args.evalType === undefined) {
+        ctx.addIssue({ code: 'custom', path: ['eval_type'], message: 'eval_type is required (evalType is the accepted camelCase alias)' });
+    }
+    else if (args.eval_type !== undefined && args.evalType !== undefined) {
+        ctx.addIssue({ code: 'custom', path: ['evalType'], message: 'pass either eval_type or evalType, not both' });
+    }
+    if (args.source_moment_id !== undefined && args.sourceMomentId !== undefined) {
+        ctx.addIssue({ code: 'custom', path: ['sourceMomentId'], message: 'pass either source_moment_id or sourceMomentId, not both' });
+    }
+});
 export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
     server.registerTool('deploy_rule', {
         title: 'Deploy Custom Rule',
         description: [
             'Deploy a new custom evaluation rule that will fire on every future evaluate_output call of its eval category.',
             '',
-            'Sibling tools — list_rules enumerates deployed rules, delete_rule removes them, evaluate_output runs them. log_trace / get_traces / delete_trace handle the trace lifecycle separately; evaluate_with_llm_judge / verify_citations run semantic scoring (not heuristic-rule-driven). deploy_rule is the WRITE path that grows the custom-rule library.',
+            'Sibling tools — list_rules enumerates deployed rules, delete_rule removes them (or disables/re-enables them with its `enabled` argument), evaluate_output runs them. log_trace / get_traces / delete_trace handle the trace lifecycle separately; evaluate_with_llm_judge / verify_citations run semantic scoring (not heuristic-rule-driven). deploy_rule is the WRITE path that grows the custom-rule library.',
             '',
-            'Behavior. Writes a row to ~/.iris/custom-rules.json (atomic write via temp file + rename) and appends a `rule.deploy` entry to the audit log (~/.iris/audit.log). The rule activates immediately for the running process and persists across restarts. Each call mints a fresh rule_id; not idempotent (deploying twice creates two rules). Tenant-scoped in Cloud tier; OSS rules are owned by LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            'Behavior. Writes a row to ~/.iris/custom-rules.json (atomic write via temp file + rename) and appends a `rule.deploy` entry to the audit log (~/.iris/audit.log). The rule activates immediately for the running process and persists across restarts. Each call mints a fresh rule_id. Rule names are unique among deployed rules: deploying a name that is already deployed is REJECTED unless `replace: true`, in which case the existing same-named rule(s) are deleted (audit `rule.delete` rows written, unregistered from the live engine) and the new rule takes their place under a new id — the response lists what was replaced. Tenant-scoped in Cloud tier; OSS rules are owned by LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
             '',
-            'Output shape. Returns JSON: `{ "rule": { "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition", "enabled": true, "createdAt", "updatedAt", "version": 1, "sourceMomentId?" } }`. The returned rule is the canonical persisted form; save the `id` if you plan to update or delete later.',
+            'Output shape. Returns JSON: `{ "rule": { "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition", "enabled": true, "createdAt", "updatedAt", "version": 1, "sourceMomentId?" }, "replaced?": [{ "id", "evalType", "severity" }], "warning?": string }`. The returned rule is the canonical persisted form; save the `id` if you plan to disable or delete later. `replaced` and `warning` appear only when `replace: true` removed an earlier rule of the same name.',
             '',
-            "Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule. The `sourceMomentId` field preserves provenance — downstream audit can trace the rule back to the moment that inspired it. Combine with evaluate_output + get_traces: 1) evaluate_output surfaces failures; 2) get_traces filters to the failure set; 3) analyze the pattern; 4) deploy_rule bakes it into the default eval path.",
+            "Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule. The `source_moment_id` field preserves provenance — downstream audit can trace the rule back to the moment that inspired it. Combine with evaluate_output + get_traces: 1) evaluate_output surfaces failures; 2) get_traces filters to the failure set; 3) analyze the pattern; 4) deploy_rule bakes it into the default eval path.",
             '',
-            "Don't use to VALIDATE a rule before committing — deploy writes immediately. Use the dashboard's preview endpoint (POST /api/v1/rules/custom/preview) for dry-run validation against sample output. Don't use to EDIT an existing rule — this call only creates; edits require a dedicated flow (coming in v0.5). To update a rule today: delete_rule then deploy_rule with the new definition.",
+            "Don't use to VALIDATE a rule before committing — deploy writes immediately. Use the dashboard's preview endpoint (POST /api/v1/rules/custom/preview) to replay a definition against recent stored traces first. To UPDATE a rule: call deploy_rule with the same name and `replace: true` (the old rule is deleted, the new one gets a fresh id), or delete_rule then deploy_rule. To pause a rule without losing it: delete_rule with `enabled: false`.",
             '',
-            'Parameters. name is 1-80 chars (Zod-enforced min/max — the same cap the persisted store applies); appears in eval_result rule_results so make it human-readable. description is optional, max 500 chars (used in dashboard tooltips). evalType determines WHEN the rule fires (must match the eval_type your evaluate_output calls use; e.g., a "completeness" rule fires on every evaluate_output where eval_type="completeness" OR eval_type="custom"). severity decides what a FAILURE of the rule does: low/medium failures only lower the weighted score (and drive dashboard sort + audit alerts); high/critical failures HARD-FAIL the evaluation — the overall `passed` is forced to false regardless of the weighted score, and the rule is listed in the response\'s `critical_failures`. Severity never changes the numeric score itself (that uses the rule\'s weight). definition.type and definition.config must match (e.g., regex_match needs config.pattern; cost_threshold needs config.max_cost; min_length needs config.min_length; max_length needs config.max_length; contains_keywords/excludes_keywords need config.keywords). Invalid configs are now REJECTED at deploy time with the offending field named, instead of deploying and then failing every evaluation. sourceMomentId is optional but recommended (preserves workflow-inversion provenance from Make-This-A-Rule composer). Defaults: severity="medium".',
+            'Parameters. Argument names are snake_case (eval_type, source_moment_id) — the camelCase spellings evalType / sourceMomentId are accepted as aliases for compatibility, but pass only one spelling of each. name is 1-80 chars (Zod-enforced min/max — the same cap the persisted store applies); appears in eval_result rule_results (alongside the rule id as `ruleId`) so make it human-readable. description is optional, max 500 chars (used in dashboard tooltips). eval_type determines WHEN the rule fires: a deployed rule runs ONLY on evaluate_output calls whose eval_type equals the rule\'s eval_type, plus eval_type="all" (which runs every bundle) — a "completeness" rule does NOT fire on eval_type="safety" or on eval_type="custom"; eval_type="custom" runs rules deployed under "custom" (and the call\'s inline custom_rules) and nothing else. severity decides what a FAILURE of the rule does: low/medium failures only lower the weighted score (and drive dashboard sort + audit alerts); high/critical failures HARD-FAIL the evaluation — the overall `passed` is forced to false regardless of the weighted score, and the rule is listed in the response\'s `critical_failures`. Severity never changes the numeric score itself (that uses the rule\'s weight). definition.type and definition.config must match (e.g., regex_match needs config.pattern; cost_threshold needs config.max_cost; min_length needs config.min_length; max_length needs config.max_length; contains_keywords/excludes_keywords need config.keywords). definition.name is optional and, if given, overwritten by the top-level name. Invalid configs are REJECTED at deploy time with the offending field named, instead of deploying and then failing every evaluation. source_moment_id is optional but recommended (preserves workflow-inversion provenance from Make-This-A-Rule composer). replace defaults to false. Defaults: severity="medium", replace=false.',
             '',
-            "Error modes. Throws 400 on invalid definition (Zod rejects — e.g., regex that fails safe-regex2 ReDoS check, or length > 1000 chars). Throws 400 on empty `name` or `name` over 80 chars. Any evalType/definition.type combination is valid (a regex_match rule can enforce a safety policy; a max_length rule can express completeness) — there is no category/type mismatch error. Returns 429 when HTTP rate limit exceeded. File-write failures (disk full, read-only fs) propagate as 500; the audit log is best-effort and does not block deploy.",
+            "Error modes. Throws 400 on invalid definition (Zod rejects — e.g., regex that fails safe-regex2 ReDoS check, or length > 1000 chars), on an unknown key inside `definition` (the valid keys are listed; config keys are free-form), on empty `name` or `name` over 80 chars, on a non-positive weight, and when both spellings of an aliased argument are passed. Throws when a rule with the same name is already deployed and `replace` is not true — the message names the existing rule id so you can delete it, replace it, or pick another name. Any eval_type/definition.type combination is valid (a regex_match rule can enforce a safety policy; a max_length rule can express completeness) — there is no category/type mismatch error. Returns 429 when HTTP rate limit exceeded. File-write failures (disk full, read-only fs) propagate as 500; the audit log is best-effort and does not block deploy.",
         ].join('\n'),
-        inputSchema: strictInput(inputSchema),
+        inputSchema: inputSchemaWithAliases,
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -81,6 +173,8 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             openWorldHint: false,
         },
     }, async (args) => {
+        const evalType = (args.eval_type ?? args.evalType);
+        const sourceMomentId = args.source_moment_id ?? args.sourceMomentId;
         // Server overrides the inner definition's `name` so it always matches
         // the user-facing rule name — same normalization the dashboard's
         // deploy route applies. Also keeps the tool's 80-char cap authoritative
@@ -90,14 +184,18 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             ...args.definition,
             name: args.name,
         };
+        // Same-name redeploy (#373) — shared with the dashboard's deploy
+        // route; see retireSameNamedRules above. Throws (nothing deployed)
+        // when the name is taken and replace is false.
+        const replaced = retireSameNamedRules(customRuleStore, evalEngine, LOCAL_TENANT, args.name, args.replace, 'mcp');
         // OSS: MCP tools operate under LOCAL_TENANT. See list-rules.ts for context.
         const rule = customRuleStore.deploy(LOCAL_TENANT, {
             name: args.name,
             description: args.description,
-            evalType: args.evalType,
+            evalType,
             severity: args.severity,
             definition,
-            sourceMomentId: args.sourceMomentId,
+            sourceMomentId,
             user: 'mcp',
         });
         // Register with the live engine so the rule fires on the very next
@@ -111,7 +209,12 @@ export function registerDeployRuleTool(server, customRuleStore, evalEngine) {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({ rule }),
+                    text: JSON.stringify({
+                        rule,
+                        ...(replaced.length > 0
+                            ? { replaced, warning: replacedRulesWarning(args.name, replaced) }
+                            : {}),
+                    }),
                 },
             ],
         };

package/dist/tools/evaluate-output.js

@@ -1,37 +1,45 @@
 import { z } from 'zod';
 import { LOCAL_TENANT } from '../types/tenant.js';
-import { strictInput } from './strict-input.js';
-const CustomRuleSchema = z.object({
-    name: z.string(),
+import { strictInput, strictNested } from './strict-input.js';
+import { assertTraceExists, insertLinkedEvalResult } from './trace-link.js';
+/*
+ * Strict one level down (#376): `{ name, type, config, wieght: 5 }` used to
+ * parse with `wieght` silently discarded, so the rule ran at weight 1 and
+ * the score moved for a reason the response could not show. `config` stays
+ * a free-form record — its keys depend on `type` and are validated by the
+ * rule itself (a broken config reports skipped + configInvalid).
+ */
+const CustomRuleSchema = strictNested({
+    name: z.string().min(1).describe('Rule name as it will appear in rule_results'),
     type: z.enum([
         'regex_match', 'regex_no_match', 'min_length', 'max_length',
         'contains_keywords', 'excludes_keywords', 'json_schema', 'cost_threshold',
-    ]),
-    config: z.record(z.string(), z.unknown()),
-    weight: z.number().optional(),
-});
+    ]).describe('Check type — decides which config keys the rule reads'),
+    config: z.record(z.string(), z.unknown()).describe('Check configuration; keys depend on type (pattern, min_length, keywords, max_cost, …)'),
+    weight: z.number().positive().optional().describe('Weight in the weighted score (default 1; must be > 0)'),
+}, 'a custom_rules entry');
 const inputSchema = {
     output: z.string().describe('The output text to evaluate (the agent\'s response that gets scored against rules)'),
     // .optional() rather than .default('completeness') so the handler can tell
     // "caller chose completeness" apart from "caller never chose" — the second
     // case gets a note in the response saying safety rules did not run. The
     // effective default is still completeness.
-    eval_type: z.enum(['completeness', 'relevance', 'safety', 'cost', 'custom']).optional().describe('Rule bundle to apply: completeness | relevance | safety | cost | custom — picks which built-in rules fire. Defaults to "completeness" when omitted (the response then carries a note that safety rules did not run)'),
-    expected: z.string().optional().describe('Expected output for comparison — REQUIRED when eval_type="relevance" (used as keyword-overlap target)'),
-    input: z.string().optional().describe('Original input for context (the ask + any source material the agent was given) — improves relevance scoring and grounds the safety bundle\'s hallucination signals'),
-    trace_id: z.string().optional().describe('Link evaluation to a trace — surfaces this eval in the dashboard\'s trace drill-through'),
+    eval_type: z.enum(['completeness', 'relevance', 'safety', 'cost', 'custom', 'all']).optional().describe('Rule bundle to apply: completeness | relevance | safety | cost | custom | all — picks which built-in rules fire. "all" runs every bundle in one call and adds a per-category breakdown. Defaults to "completeness" when omitted (the response then carries a note that safety rules did not run)'),
+    expected: z.string().optional().describe('Expected output for comparison — consulted only by the completeness bundle\'s expected_coverage rule; NOT used by relevance (the relevance rules compare the output against `input`)'),
+    input: z.string().optional().describe('Original input for context (the ask + any source material the agent was given) — REQUIRED when eval_type="relevance" (keyword_overlap and topic_consistency compare the output against it and skip without it); also grounds the safety bundle\'s hallucination signals'),
+    trace_id: z.string().optional().describe('Link evaluation to a trace — surfaces this eval in the dashboard\'s trace drill-through. Must be the id of a stored trace (from log_trace / get_traces); an unknown id is rejected before anything is evaluated'),
     // .max(10): inline rules skip the deploy-time probe, and the engine runs
     // rules synchronously — without a cap, one request carrying N sandbox-
     // defeating regex rules stalls the server linearly in N (measured 9.3s at
     // N=50). Ten is ample for per-call rules; persistent sets belong in
     // deploy_rule, where deploy-time validation probes each pattern.
-    custom_rules: z.array(CustomRuleSchema).max(10).optional().describe('Custom evaluation rules, max 10 per call (deploy persistent rule sets via deploy_rule instead) — fires REGARDLESS of eval_type; pass eval_type="custom" if you want ONLY these'),
-    cost_usd: z.number().optional().describe('Cost in USD — only consulted when eval_type="cost" (compared against cost_threshold rules)'),
+    custom_rules: z.array(CustomRuleSchema).max(10).optional().describe('Custom evaluation rules, max 10 per call (deploy persistent rule sets via deploy_rule instead) — fires REGARDLESS of eval_type; pass eval_type="custom" if you want ONLY these. Each entry accepts exactly name, type, config, weight — an unknown key (e.g. a misspelled weight) is rejected'),
+    cost_usd: z.number().optional().describe('Cost in USD — consulted by the cost bundle (eval_type="cost" or "all") AND by any cost_threshold custom rule regardless of eval_type; omit it and such a rule skips rather than passes (a critical one is listed in critical_skipped)'),
     token_usage: z.object({
         prompt_tokens: z.number().optional(),
         completion_tokens: z.number().optional(),
         total_tokens: z.number().optional(),
-    }).optional().describe('Token usage breakdown — only consulted when eval_type="cost" (used for token-budget rules)'),
+    }).optional().describe('Token usage breakdown — only consulted by the cost bundle (eval_type="cost" or "all"; used for token-budget rules)'),
 };
 export function registerEvaluateOutputTool(server, storage, evalEngine) {
     server.registerTool('evaluate_output', {
@@ -43,17 +51,17 @@ export function registerEvaluateOutputTool(server, storage, evalEngine) {
             '',
             'Behavior. Deterministic, in-process scoring — same inputs always produce the same result. Writes one eval_result row to Iris storage (linked to trace_id if provided; unlinked otherwise). No external network calls in heuristic mode (v0.4 adds an llm_as_judge eval_type that DOES call LLM APIs; see the separate evaluate_with_llm_judge tool for that). Rate-limited to 20 req/min on HTTP MCP, unlimited on stdio. Runs in ~5-50ms for rule-based evaluation.',
             '',
-            'Output shape. Returns JSON: `{ "id": "<uuid>", "eval_type": "<bundle that ran>", "score": 0..1, "passed": boolean, "critical_failures?": string[], "rule_results": [{ "ruleName", "passed", "score", "message", "skipped?" }], "suggestions": string[], "rules_evaluated": number, "rules_skipped": number, "insufficient_data": boolean, "note?": string }`. `insufficient_data=true` means no applicable rules fired (e.g., safety eval with only cost data). `note` appears only when eval_type was omitted, naming the defaulted bundle and that safety rules did not run.',
+            'Output shape. Returns JSON: `{ "id": "<uuid>", "eval_type": "<bundle that ran>", "score": 0..1, "passed": boolean, "critical_failures?": string[], "critical_skipped?": string[], "rule_results": [{ "ruleName", "ruleId?", "category?", "passed", "score", "message", "skipped?", "skipReason?", "budgetExceeded?", "configInvalid?" }], "suggestions": string[], "rules_evaluated": number, "rules_skipped": number, "insufficient_data": boolean, "categories?": { "<bundle>": { "score", "passed", "rules_evaluated", "rules_skipped", "insufficient_data", "critical_failures?", "critical_skipped?" } }, "note?": string }`. `ruleId` is present on results produced by a deployed rule (rule-XXXX) so two rules sharing a name stay distinguishable. `categories` appears only for eval_type="all" and carries one entry per bundle that had rules, each with the same threshold + critical-veto semantics as a single-bundle run; `category` on each rule result says which bundle it came from. `insufficient_data=true` means no applicable rules fired (e.g., safety eval with only cost data). `note` appears only when eval_type was omitted, naming the defaulted bundle and that safety rules did not run.',
             '',
-            'What `passed` means. `score` and `passed` answer different questions. `score` is the weighted average across the rules that ran — a 0..1 quality gradient. `passed` is the ship/no-ship verdict: true only when the score clears the pass threshold (default 0.7, configurable via config `eval.defaultThreshold`) AND no critical rule failed. Critical rules HARD-FAIL: if one fails, `passed` is false regardless of the weighted score, and the culprits are listed in `critical_failures`. The critical rules are the genuine safety violations — `no_pii`, `no_injection_patterns`, `no_blocklist_words` — plus any deployed custom rule with severity high/critical. A leaked SSN can never be averaged away by other rules passing.',
+            'What `passed` means. `score` and `passed` answer different questions. `score` is the weighted average across the rules that ran — a 0..1 quality gradient. `passed` is the ship/no-ship verdict: true only when the score clears the pass threshold (default 0.7, configurable via config `eval.defaultThreshold`) AND no critical rule failed. Critical rules HARD-FAIL: if one fails, `passed` is false regardless of the weighted score, and the culprits are listed in `critical_failures`. The critical rules are the genuine safety violations — `no_pii`, `no_injection_patterns`, `no_blocklist_words` — plus any deployed custom rule with severity high/critical. A leaked SSN can never be averaged away by other rules passing. For eval_type="all" the veto spans every bundle: one critical failure anywhere forces the overall `passed` to false. One caveat, stated because it is reachable on purpose: a critical rule that SKIPPED did not judge the output and therefore cannot veto — a regex rule whose match blew the 100ms sandbox budget on crafted output skips, so `passed` can be true with no `critical_failures`. Every such rule is named in `critical_skipped`. If your gate must fail closed, treat a non-empty `critical_skipped` as UNKNOWN, not clean.',
             '',
-            'Use when you want a quality score on a specific output — typically after log_trace records the execution. Pass `eval_type` to route to the right rule bundle: `completeness` (length, sentence count, relevance to input), `relevance` (keyword overlap, topic consistency), `safety` (PII leak, prompt injection, hallucination markers, stub-output detection — pass `input` so the hallucination signals can cross-check the output against the material the agent was given), `cost` (budget threshold), or `custom` (bring your own rules via `custom_rules`).',
+            'Use when you want a quality score on a specific output — typically after log_trace records the execution. Pass `eval_type` to route to the right rule bundle: `completeness` (length, non-empty output, sentence count, coverage of `expected`), `relevance` (keyword overlap and topic consistency against `input`), `safety` (PII leak, prompt injection, hallucination markers, stub-output detection — pass `input` so the hallucination signals can cross-check the output against the material the agent was given), `cost` (budget threshold), `custom` (bring your own rules via `custom_rules`), or `all` (every bundle above in one call — completeness, relevance, safety, cost, plus rules deployed under "custom" and any inline custom_rules — with per-category scores in `categories` and one overall verdict; rules whose context is missing, such as relevance without `input` or cost without `cost_usd`, skip and are excluded from the score exactly as in a single-bundle run).',
             '',
             'Don\'t use when the output is empty or has no applicable rules — the eval_type decides which rules apply, and invalid combinations return score=0 + insufficient_data=true (not an error, but not actionable). Don\'t use to VALIDATE JSON schemas directly (use your language\'s JSON Schema validator — Iris\'s `json_schema` custom rule type is for output-shape assertions, not arbitrary validation).',
             '',
-            'Parameters. expected is REQUIRED when eval_type="relevance" (used as the comparison target for keyword overlap + topic consistency); ignored for other eval_types. cost_usd + token_usage are ONLY consulted when eval_type="cost" (ignored otherwise). custom_rules ALWAYS fires regardless of eval_type — pass eval_type="custom" if you want ONLY your rules to run (otherwise both your rules AND the eval_type bundle run together). trace_id is optional but recommended (linking the eval to its trace surfaces it in the dashboard\'s drill-through). input adds context to keyword-overlap relevance checks AND grounds the safety bundle\'s hallucination signals (without it those signals stay silent rather than guess); ignored otherwise. Defaults: eval_type="completeness" — and when you rely on that default, the response carries a `note` reminding you that the safety bundle did not run.',
+            'Parameters. input is REQUIRED when eval_type="relevance" (keyword_overlap and topic_consistency compare the output against it; without it both rules skip and the response reports insufficient_data=true) AND grounds the safety bundle\'s hallucination signals (without it those signals stay silent rather than guess); ignored otherwise. expected is consulted only by the completeness bundle\'s expected_coverage rule; ignored for other eval_types — it is NOT the relevance target. cost_usd is consulted by the cost bundle AND by any cost_threshold custom rule regardless of eval_type — omit it and such a rule skips rather than passes (a critical one is listed in critical_skipped); token_usage is ONLY consulted by the cost bundle. custom_rules ALWAYS fires regardless of eval_type — pass eval_type="custom" if you want ONLY your rules to run (otherwise both your rules AND the eval_type bundle run together); each entry takes exactly name, type, config and weight. trace_id is optional but recommended (linking the eval to its trace surfaces it in the dashboard\'s drill-through) and must name a stored trace. Defaults: eval_type="completeness" — and when you rely on that default, the response carries a `note` reminding you that the safety bundle did not run.',
             '',
-            'Error modes. Throws on unknown argument names (strict schema — a misspelled argument is rejected with the valid argument list, never silently dropped). Throws on malformed custom_rules (Zod rejects) and on more than 10 custom_rules in one call (use deploy_rule for persistent rule sets). Returns 400 on regex patterns that fail safe-regex2 ReDoS check or exceed 1000-char limit. Returns 429 when HTTP rate limit exceeded. Storage failures propagate as 500. The eval itself never throws — failing rules report `passed: false` with a message, they don\'t bubble exceptions. A regex that exceeds the 100ms sandbox matching budget on a given output reports skipped with budgetExceeded=true instead of hanging the server (fail-open per rule — gate on that flag if you must fail closed).',
+            'Error modes. Throws on unknown argument names (strict schema — a misspelled argument is rejected with the valid argument list, never silently dropped), and likewise on an unknown key inside a custom_rules entry (e.g. `wieght`) — the valid keys are listed; a rule\'s `config` keys are free-form and are not checked here. Throws on malformed custom_rules (Zod rejects the shape: missing name/type, unknown type, non-object config, non-positive weight) and on more than 10 custom_rules in one call (use deploy_rule for persistent rule sets). Throws when trace_id does not match a stored trace — checked BEFORE evaluating, so nothing is scored or written; the message names the trace_id. An inline rule whose CONFIG is unusable — a regex that fails the safe-regex2 ReDoS check or exceeds the 1000-char limit, a missing or non-string config.pattern, non-string keywords — does NOT error: that rule reports skipped with configInvalid=true and a skipReason naming the field, and the other rules still run (deploy_rule rejects the same configs with a 400 at deploy time). Returns 429 when HTTP rate limit exceeded. Storage failures propagate as 500. The eval itself never throws — failing rules report `passed: false` with a message, they don\'t bubble exceptions. A regex that exceeds the 100ms sandbox matching budget on a given output reports skipped with budgetExceeded=true instead of hanging the server (fail-open per rule — gate on that flag if you must fail closed).',
         ].join('\n'),
         inputSchema: strictInput(inputSchema),
         annotations: {
@@ -63,25 +71,34 @@ export function registerEvaluateOutputTool(server, storage, evalEngine) {
             openWorldHint: false, // No external network in heuristic mode; LLM-as-judge has its own tool with openWorldHint:true
         },
     }, async (args) => {
+        // Refuse an unknown trace_id up front (#376): the old path ran the
+        // evaluation and then surfaced SQLite's "FOREIGN KEY constraint
+        // failed", which names neither the field nor the fix.
+        if (args.trace_id) {
+            await assertTraceExists(storage, LOCAL_TENANT, args.trace_id);
+        }
         // Track omission explicitly: a caller who never chose a bundle gets
         // the completeness default AND a note saying so — six of seven UAT
         // personas read passed:true on PII-laden text with no hint that the
         // safety bundle never ran.
         const evalTypeOmitted = args.eval_type === undefined;
-        const evalType = (args.eval_type ?? 'completeness');
-        const result = evalEngine.evaluate(evalType, {
+        const context = {
             output: args.output,
             expected: args.expected,
             input: args.input,
             costUsd: args.cost_usd,
             tokenUsage: args.token_usage,
-        }, args.custom_rules);
+        };
+        const customRules = args.custom_rules;
+        const result = args.eval_type === 'all'
+            ? evalEngine.evaluateAll(context, customRules)
+            : evalEngine.evaluate((args.eval_type ?? 'completeness'), context, customRules);
         if (args.trace_id) {
             result.trace_id = args.trace_id;
         }
         // OSS single-tenant: MCP tool callers are the local user. Cloud
         // will derive tenant from the authenticated MCP session.
-        await storage.insertEvalResult(LOCAL_TENANT, result);
+        await insertLinkedEvalResult(storage, LOCAL_TENANT, result);
         return {
             content: [
                 {
@@ -95,14 +112,23 @@ export function registerEvaluateOutputTool(server, storage, evalEngine) {
                         score: result.score,
                         passed: result.passed,
                         ...(result.critical_failures ? { critical_failures: result.critical_failures } : {}),
+                        // The other half of the veto contract. The engine names every
+                        // critical rule that SKIPPED (budget-killed regex, missing cost
+                        // data) so a fail-closed gate can treat the eval as unknown;
+                        // this response used to drop the field, so the gate the
+                        // description tells users to write keyed on something that
+                        // never arrived and read passed:true as clean.
+                        ...(result.critical_skipped ? { critical_skipped: result.critical_skipped } : {}),
                         rule_results: result.rule_results,
                         suggestions: result.suggestions,
                         rules_evaluated: result.rules_evaluated,
                         rules_skipped: result.rules_skipped,
                         insufficient_data: result.insufficient_data,
+                        // Per-bundle breakdown — eval_type="all" only.
+                        ...(result.categories ? { categories: result.categories } : {}),
                         ...(evalTypeOmitted
                             ? {
-                                note: 'eval_type was omitted, so the default "completeness" bundle ran. Safety rules (PII, injection, blocklist, stub, hallucination) were NOT part of this evaluation — pass eval_type="safety" to run them.',
+                                note: 'eval_type was omitted, so the default "completeness" bundle ran. Safety rules (PII, injection, blocklist, stub, hallucination) were NOT part of this evaluation — pass eval_type="safety" to run them, or eval_type="all" to run every bundle.',
                             }
                             : {}),
                     }),

package/dist/tools/evaluate-with-llm-judge.js

@@ -4,6 +4,7 @@ import { evaluateWithLLMJudge } from '../eval/llm-judge/evaluator.js';
 import { findPricing } from '../eval/llm-judge/pricing.js';
 import { generateEvalId } from '../utils/ids.js';
 import { strictInput } from './strict-input.js';
+import { assertTraceExists, insertLinkedEvalResult } from './trace-link.js';
 const inputSchema = {
     output: z.string().min(1).describe('The agent output text to evaluate'),
     template: z
@@ -16,7 +17,7 @@ const inputSchema = {
     input: z.string().optional().describe('User question / prompt that produced the output (improves accuracy for helpfulness/safety)'),
     expected: z.string().optional().describe('Reference answer (required for correctness template)'),
     source_material: z.string().optional().describe('Provided RAG sources (required for faithfulness template)'),
-    trace_id: z.string().optional().describe('Link this evaluation to a trace'),
+    trace_id: z.string().optional().describe('Link this evaluation to a stored trace (id from log_trace / get_traces); an unknown id is rejected BEFORE the judge is called'),
     max_cost_usd: z.number().positive().optional().describe('Cost cap in USD; defaults to IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL or 0.25'),
     max_output_tokens: z.number().int().positive().max(4096).optional().describe('Judge output token cap; default 512'),
     temperature: z.number().min(0).max(2).optional().describe('Sampling temperature; default 0 (deterministic)'),
@@ -70,9 +71,9 @@ export function registerEvaluateWithLLMJudgeTool(server, storage) {
             '',
             "Don't use for simple regex/length/keyword checks (use evaluate_output with heuristic rules — they're free, deterministic, 1000x faster). Don't use without an API key set (IRIS_ANTHROPIC_API_KEY or IRIS_OPENAI_API_KEY). Don't use on very large outputs (>8K tokens) without raising max_cost_usd — the pre-check will refuse the call.",
             '',
-            'Parameters. model is required (no default — pick consciously since cost varies 100x across models). provider is auto-detected from the model name; override only for ambiguous IDs. expected is REQUIRED when template="correctness" (the reference answer to compare against); ignored for other templates. source_material is REQUIRED when template="faithfulness" (the RAG sources to ground against); ignored otherwise. input is optional but improves scoring on helpfulness/safety templates (gives the judge the user prompt that produced the output). max_cost_usd defaults to env var IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL or $0.25 — the worst-case cost is computed BEFORE the call (input_tokens × prompt_price + max_output_tokens × completion_price); call refused upfront if it would exceed. max_output_tokens caps the judge response (default 512, max 4096); higher = more rationale detail + more cost. temperature default 0 (deterministic). timeout_ms default 60000. trace_id optional but recommended (links eval to trace in dashboard). Defaults: temperature=0, max_output_tokens=512, max_cost_usd=$0.25, timeout_ms=60000.',
+            'Parameters. model is required (no default — pick consciously since cost varies 100x across models). provider is auto-detected from the model name; override only for ambiguous IDs. expected is REQUIRED when template="correctness" (the reference answer to compare against); ignored for other templates. source_material is REQUIRED when template="faithfulness" (the RAG sources to ground against); ignored otherwise. input is optional but improves scoring on helpfulness/safety templates (gives the judge the user prompt that produced the output). max_cost_usd defaults to env var IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL or $0.25 — the worst-case cost is computed BEFORE the call (input_tokens × prompt_price + max_output_tokens × completion_price, PLUS the same for the one retry that fires if the judge\'s first reply is not valid JSON); call refused upfront if that two-attempt worst case would exceed. When a retry does run, the reported input_tokens / output_tokens / cost_usd / latency_ms are totals across both attempts. max_output_tokens caps the judge response (default 512, max 4096); higher = more rationale detail + more cost. temperature default 0 (deterministic). timeout_ms default 60000. trace_id optional but recommended (links eval to trace in dashboard). Defaults: temperature=0, max_output_tokens=512, max_cost_usd=$0.25, timeout_ms=60000.',
             '',
-            'Error modes. Throws when the required API key env var is missing. Throws when the estimated worst-case cost exceeds max_cost_usd (raise the cap or trim prompts). Throws LLMJudgeError on provider errors — kind=`auth` on 401/403, `rate_limit` on 429 (auto-retried once), `server_error` on 5xx, `timeout` on abort, `malformed_response` when the judge fails to emit valid JSON on both attempts. Throws "Unknown model" for unsupported model IDs — update src/eval/llm-judge/pricing.ts first.',
+            'Error modes. Throws when the required API key env var is missing. Throws when trace_id does not match a stored trace — checked before the provider call, so no money is spent and nothing is written. Throws when the estimated worst-case cost exceeds max_cost_usd (raise the cap or trim prompts). Throws LLMJudgeError on provider errors — kind=`auth` on 401/403, `rate_limit` on 429 (auto-retried once), `server_error` on 5xx, `timeout` on abort, `malformed_response` when the judge fails to emit valid JSON on both attempts. Throws "Unknown model" for unsupported model IDs — update src/eval/llm-judge/pricing.ts first.',
         ].join('\n'),
         inputSchema: strictInput(inputSchema),
         annotations: {
@@ -85,6 +86,12 @@ export function registerEvaluateWithLLMJudgeTool(server, storage) {
         const provider = args.provider ?? inferProvider(args.model);
         const apiKey = resolveApiKey(provider);
         const maxCostUsd = resolveMaxCost(args.max_cost_usd);
+        // An unknown trace_id is refused BEFORE the provider call — the old
+        // path spent the judge's money and then failed the INSERT with a raw
+        // "FOREIGN KEY constraint failed" (#376).
+        if (args.trace_id) {
+            await assertTraceExists(storage, LOCAL_TENANT, args.trace_id);
+        }
         const result = await evaluateWithLLMJudge({
             output: args.output,
             template: args.template,
@@ -105,7 +112,7 @@ export function registerEvaluateWithLLMJudgeTool(server, storage) {
         // judge doesn't fit completeness/relevance/safety/cost taxonomy
         // cleanly — it spans all four. The rule_results payload carries
         // the full judge provenance.
-        await storage.insertEvalResult(LOCAL_TENANT, {
+        await insertLinkedEvalResult(storage, LOCAL_TENANT, {
             id: evalId,
             trace_id: args.trace_id,
             eval_type: 'custom',

package/dist/tools/get-traces.d.ts

@@ -1,3 +1,30 @@
+import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IStorageAdapter } from '../types/query.js';
+export declare function isIsoTimestamp(value: string): boolean;
+/**
+ * The `since` / `until` field schema. Shared with the dashboard's trace
+ * query (dashboard/validation.ts) so both read paths refuse the same
+ * unparseable bounds with the same hint.
+ */
+export declare const isoTimestamp: z.ZodString;
+/** The cross-field bounds a trace query can carry. */
+export interface TraceRangeArgs {
+    min_score?: number;
+    max_score?: number;
+    since?: string;
+    until?: string;
+}
+/**
+ * Cross-field checks the per-field schema cannot express (#373). A range
+ * whose bounds cross — min_score 0.9 / max_score 0.1, or since after until
+ * — used to be accepted and return an empty page, which reads as "no such
+ * traces" when the truth is "no trace could ever match this". Refusing it
+ * with the two values named is what the argument descriptions promise.
+ *
+ * One function for both read paths: `get_traces` (MCP) and
+ * `GET /api/v1/traces` (dashboard) call it from their `superRefine`, so a
+ * bound the tool rejects is never one the HTTP query quietly accepts.
+ */
+export declare function addTraceRangeIssues(args: TraceRangeArgs, ctx: z.RefinementCtx): void;
 export declare function registerGetTracesTool(server: McpServer, storage: IStorageAdapter): void;

package/dist/tools/get-traces.js

@@ -1,22 +1,74 @@
 import { z } from 'zod';
 import { LOCAL_TENANT } from '../types/tenant.js';
 import { strictInput } from './strict-input.js';
+/*
+ * An ISO-8601 instant (2026-08-01T00:00:00Z, offsets allowed) or calendar
+ * date (2026-08-01). Stored timestamps are ISO strings and the adapter
+ * compares them lexically, so both forms bound the query correctly; a
+ * date-only value is the natural "since the 1st" spelling and is kept
+ * rather than forced into a full timestamp.
+ */
+const isoInstant = z.iso.datetime({ offset: true });
+const isoDate = z.iso.date();
+export function isIsoTimestamp(value) {
+    return isoInstant.safeParse(value).success || isoDate.safeParse(value).success;
+}
+const TIMESTAMP_HINT = 'must be an ISO 8601 timestamp (e.g. 2026-08-01T00:00:00Z) or date (2026-08-01)';
+/**
+ * The `since` / `until` field schema. Shared with the dashboard's trace
+ * query (dashboard/validation.ts) so both read paths refuse the same
+ * unparseable bounds with the same hint.
+ */
+export const isoTimestamp = z.string().refine(isIsoTimestamp, {
+    // The rejected value is echoed so the error names what was sent, as the
+    // crossed-bound errors already do (v0.6.0 acceptance pass, B8/C9).
+    error: (issue) => `${JSON.stringify(issue.input)} ${TIMESTAMP_HINT}`,
+});
+/**
+ * Cross-field checks the per-field schema cannot express (#373). A range
+ * whose bounds cross — min_score 0.9 / max_score 0.1, or since after until
+ * — used to be accepted and return an empty page, which reads as "no such
+ * traces" when the truth is "no trace could ever match this". Refusing it
+ * with the two values named is what the argument descriptions promise.
+ *
+ * One function for both read paths: `get_traces` (MCP) and
+ * `GET /api/v1/traces` (dashboard) call it from their `superRefine`, so a
+ * bound the tool rejects is never one the HTTP query quietly accepts.
+ */
+export function addTraceRangeIssues(args, ctx) {
+    if (args.min_score !== undefined && args.max_score !== undefined && args.min_score > args.max_score) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['min_score'],
+            message: `min_score (${args.min_score}) must be <= max_score (${args.max_score}) — the range is empty and no trace could match it`,
+        });
+    }
+    if (args.since !== undefined && args.until !== undefined && Date.parse(args.since) > Date.parse(args.until)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['since'],
+            message: `since (${args.since}) must not be later than until (${args.until}) — the window is empty and no trace could match it`,
+        });
+    }
+}
 const inputSchema = {
     agent_name: z.string().optional().describe('Filter by agent name — exact match (no wildcards in v0.4)'),
     framework: z.string().optional().describe('Filter by agent framework — exact match (e.g., langchain, autogen)'),
-    since: z.string().optional().describe('ISO timestamp lower bound — return traces with timestamp >= this'),
-    until: z.string().optional().describe('ISO timestamp upper bound — return traces with timestamp < this'),
-    min_score: z.number().optional().describe('Minimum eval score filter (0..1) — applied to LATEST eval per trace, not all evals'),
-    max_score: z.number().optional().describe('Maximum eval score filter (0..1) — applied to LATEST eval per trace'),
+    since: isoTimestamp.optional().describe('ISO 8601 timestamp (or date) lower bound — return traces with timestamp >= this; anything that is not an ISO timestamp is rejected, never treated as "no bound"'),
+    until: isoTimestamp.optional().describe('ISO 8601 timestamp (or date) upper bound — return traces with timestamp <= this; must not be earlier than `since`'),
+    min_score: z.number().min(0).max(1).optional().describe('Minimum eval score filter (0..1; values outside are rejected) — applied to LATEST eval per trace, not all evals; must be <= max_score when both are set'),
+    max_score: z.number().min(0).max(1).optional().describe('Maximum eval score filter (0..1; values outside are rejected) — applied to LATEST eval per trace'),
     // Mirrors traceQuerySchema in dashboard/validation.ts — both capture paths
     // (MCP tool, HTTP query) enforce the same 1..1000 bound. Unclamped, limit:-1
     // meant "LIMIT -1" in SQLite, i.e. every row (#332).
     limit: z.number().int().min(1).max(1000).default(50).describe('Results per page (default 50, max 1000 — values >1000 return 400)'),
-    offset: z.number().default(0).describe('Zero-based pagination offset — skip first N results'),
+    offset: z.number().int().min(0).default(0).describe('Zero-based pagination offset — skip first N results (non-negative integer)'),
     sort_by: z.enum(['timestamp', 'latency_ms', 'cost_usd']).default('timestamp').describe('Sort by timestamp | latency_ms | cost_usd (default timestamp)'),
     sort_order: z.enum(['asc', 'desc']).default('desc').describe('Sort order: asc | desc (default desc — most recent / highest first)'),
     include_summary: z.boolean().default(false).describe('Include dashboard summary stats in same response — saves a round-trip when ingesting for dashboards'),
 };
+// Cross-field range checks — see addTraceRangeIssues above.
+const inputSchemaWithRanges = strictInput(inputSchema).superRefine(addTraceRangeIssues);
 export function registerGetTracesTool(server, storage) {
     server.registerTool('get_traces', {
         title: 'Get Traces',
@@ -33,11 +85,11 @@ export function registerGetTracesTool(server, storage) {
             '',
             'Don\'t use to score a trace (use evaluate_output). Don\'t use to create a trace (use log_trace). Don\'t use as a live event stream — it\'s a query, not a subscription; poll with exponential backoff or use the dashboard\'s SSE endpoint for real-time.',
             '',
-            'Parameters. limit defaults to 50, max 1000 (anything higher returns 400). offset is zero-based pagination. min_score / max_score filter on the LATEST eval per trace, not all evals (so a trace with one failing + one passing eval may or may not match depending on which landed last). Combining since + sort_by="latency_ms" + sort_order="desc" is the canonical "find slow recent traces" query. include_summary returns dashboard-style aggregates in the SAME response (saves a round-trip; use true for dashboard ingest, false for analytics queries that don\'t need them). agent_name and framework are exact-match (no wildcards in v0.4). Defaults: limit=50, offset=0, sort_by="timestamp", sort_order="desc", include_summary=false.',
+            'Parameters. limit defaults to 50, max 1000 (anything higher returns 400). offset is zero-based pagination (non-negative integer). since / until must be ISO 8601 timestamps or dates — `since` is inclusive (timestamp >= since), `until` is inclusive (timestamp <= until), and `since` may not be later than `until`. min_score / max_score are 0..1 and filter on the LATEST eval per trace, not all evals (so a trace with one failing + one passing eval may or may not match depending on which landed last); min_score may not exceed max_score. Combining since + sort_by="latency_ms" + sort_order="desc" is the canonical "find slow recent traces" query. include_summary returns dashboard-style aggregates in the SAME response (saves a round-trip; use true for dashboard ingest, false for analytics queries that don\'t need them). agent_name and framework are exact-match (no wildcards in v0.4). Defaults: limit=50, offset=0, sort_by="timestamp", sort_order="desc", include_summary=false.',
             '',
-            'Error modes. Returns 400 on invalid sort_by / sort_order (Zod enum). Returns 400 if limit > 1000. Returns 429 when HTTP rate limit exceeded. Storage failures propagate as 500. Empty result with `total: 0` on no matches (not an error).',
+            'Error modes. Returns 400 on invalid sort_by / sort_order (Zod enum). Returns 400 if limit > 1000 or offset < 0. Returns 400 — naming both values — on an empty range: min_score > max_score, since later than until, a score outside 0..1, or a since/until that is not an ISO 8601 timestamp or date (an unparseable bound is refused, never silently ignored). Returns 429 when HTTP rate limit exceeded. Storage failures propagate as 500. Empty result with `total: 0` on no matches (not an error).',
         ].join('\n'),
-        inputSchema: strictInput(inputSchema),
+        inputSchema: inputSchemaWithRanges,
         annotations: {
             readOnlyHint: true, // Pure query: never writes, never deletes
             destructiveHint: false, // Inverse of readOnly — trivially false