@iris-eval/mcp-server 0.8.1 → 0.9.0

package/dist/tools/index.js

@@ -7,9 +7,30 @@ import { registerDeleteRuleTool } from './delete-rule.js';
 import { registerDeleteTraceTool } from './delete-trace.js';
 import { registerEvaluateWithLLMJudgeTool } from './evaluate-with-llm-judge.js';
 import { registerVerifyCitationsTool } from './verify-citations.js';
+import { dormantRulesFrom } from '../eval/dormant.js';
+import { LOCAL_TENANT } from '../types/tenant.js';
+/**
+ * Every tool this server registers, by name. The capabilities object
+ * lists it, the docs contract checks prose against it, and a test asserts
+ * it equals what tools/list returns — so a tool added below without a
+ * name here (or the reverse) fails before it ships.
+ */
+export const TOOL_NAMES = [
+    'log_trace',
+    'evaluate_output',
+    'get_traces',
+    'list_rules',
+    'deploy_rule',
+    'delete_rule',
+    'delete_trace',
+    'evaluate_with_llm_judge',
+    'verify_citations',
+];
 export function registerAllTools(server, storage, evalEngine, customRuleStore) {
     registerLogTraceTool(server, storage);
-    registerEvaluateOutputTool(server, storage, evalEngine);
+    registerEvaluateOutputTool(server, storage, evalEngine, {
+        dormant: () => dormantRulesFrom(customRuleStore.quarantined(LOCAL_TENANT)),
+    });
     registerGetTracesTool(server, storage);
     registerListRulesTool(server, customRuleStore, evalEngine);
     registerDeployRuleTool(server, customRuleStore, evalEngine);

package/dist/tools/list-rules.d.ts

@@ -1,4 +1,17 @@
+import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CustomRuleStore } from '../custom-rule-store.js';
 import type { EvalEngine } from '../eval/engine.js';
+export declare const listRulesOutputSchema: z.ZodObject<{
+    rules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$loose>>;
+    total: z.ZodNumber;
+    enabled_count: z.ZodNumber;
+    built_in: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$loose>>;
+    quarantined: z.ZodArray<z.ZodUnknown>;
+}, z.core.$loose>;
 export declare function registerListRulesTool(server: McpServer, customRuleStore: CustomRuleStore, evalEngine: EvalEngine): void;

package/dist/tools/list-rules.js

@@ -1,59 +1,66 @@
 /*
- * list_rules MCP tool — enumerate deployed custom rules.
+ * list_rules MCP tool — the rule inventory.
  *
- * Read-only view into the custom-rule store (~/.iris/custom-rules.json).
- * Lets agents discover what rules are deployed, what each one evaluates,
- * and which are enabled — so an agent can decide whether to call
- * evaluate_output at all, and which eval_type to route through.
- *
- * Companion to deploy_rule / delete_rule. Together these replace the
- * dashboard-only Make-This-A-Rule composer when an agent (not a human)
- * needs to manage the rule set programmatically.
+ * Two halves. `built_in` is the shipped roster with everything a caller
+ * needs to trust a verdict: what each rule is (kind, mechanism), what it
+ * reads (needs — absent means it skips), the question it answers, the
+ * criticality THIS server applies and who decided it, and its published
+ * accuracy. `rules` is the custom-rule store (~/.iris/custom-rules.json),
+ * the read path deploy_rule and delete_rule write to.
  */
 import { z } from 'zod';
 import { builtInRuleRoster } from '../eval/criticality.js';
+import { ruleProof } from '../capabilities.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
 import { strictInput } from './strict-input.js';
+import { describeTool, ERROR_ENVELOPE_SENTENCE } from './describe.js';
+import { guarded, respond } from './respond.js';
+import { PROOF_RESOURCE_URI } from '../resources/uris.js';
 const inputSchema = {
     eval_type: z
         .enum(['completeness', 'relevance', 'safety', 'cost', 'custom'])
         .optional()
-        .describe('Filter to rules of a specific eval category'),
+        .describe('Filter the custom rules to one eval category (exact match); built_in is never filtered'),
     enabled_only: z
         .boolean()
         .default(false)
-        .describe('Return only enabled rules (excludes disabled ones)'),
+        .describe('Return only enabled custom rules (a rule disabled with delete_rule stays in the store and does not fire)'),
 };
+export const listRulesOutputSchema = z.looseObject({
+    rules: z.array(z.looseObject({ id: z.string(), name: z.string() })).describe('the deployed custom rules after the filters: id, name, description, evalType, severity, definition, enabled, createdAt, updatedAt, version, sourceMomentId'),
+    total: z.number().int().describe('custom rules after the filters'),
+    enabled_count: z.number().int().describe('of those, how many are enabled'),
+    built_in: z.array(z.looseObject({ name: z.string() })).describe('the shipped roster, never filtered: name, category, description, weight, kind, mechanism, needs, question, classes, version, the EFFECTIVE critical flag with criticalSource, and proof (published precision, recall, intervals and ppvAt from https://iris-eval.com/proof; null where the proof is a conformance check)'),
+    quarantined: z.array(z.unknown()).describe('entries in the store this version could not validate; they do not fire and are never deleted by a deploy'),
+});
 export function registerListRulesTool(server, customRuleStore, evalEngine) {
     server.registerTool('list_rules', {
-        title: 'List Custom Rules',
-        description: [
-            'Enumerate deployed custom evaluation rules from the local rule store.',
-            '',
-            'Sibling tools — deploy_rule adds custom rules, delete_rule removes them, evaluate_output runs them against agent output. log_trace / get_traces / delete_trace handle the trace lifecycle separately. list_rules is the READ path for the custom-rule store; nothing else exposes the inventory.',
-            '',
-            'Behavior. Pure read of ~/.iris/custom-rules.json (in-memory cached; no disk read per call after server boot). No mutation, no external network. Tenant-scoped in Cloud tier; OSS returns all rules for the single local tenant. Rate-limited to 20 req/min on HTTP MCP, unlimited on stdio. Returns in <5ms.',
-            '',
-            'Output shape. Returns JSON: `{ "rules": [{ "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition": { name, type, config, weight? }, "enabled": boolean, "createdAt": ISO timestamp, "updatedAt": ISO timestamp, "version": number, "sourceMomentId?": string }], "total": number, "enabled_count": number, "built_in": [{ "name", "category", "weight", "critical": boolean, "criticalSource": "default" | "config" }] }`. Empty `rules` array + total=0 when no custom rules are deployed. A deployed rule fires only on evaluate_output calls whose eval_type equals its evalType (or eval_type="all", which runs every bundle). `built_in` is the shipped rule set, always present and NOT narrowed by the filters; `total` and `enabled_count` count custom rules only.',
-            '',
-            'Why `built_in` carries criticality. A critical rule vetoes `passed` regardless of the weighted score, and which built-in rules are critical is configurable (`eval.criticalRules` / `eval.nonCriticalRules`). `critical` is the EFFECTIVE value this server applies and `criticalSource` says who decided it: `default` is the declaration on the rule itself, `config` means one of those lists named it. Read it before trusting a `passed: true` — it is how you tell "nothing was violated" from "the rule that would have vetoed is demoted on this server".',
-            '',
-            'Use when you need to know what custom rules are currently live (before calling evaluate_output, before deploying a similar rule to avoid duplicates, or when building a dashboard view). Filter with `eval_type` to scope to a specific category, or `enabled_only: true` to exclude disabled rules. Use get_traces to see trace data; use evaluate_output to run scoring; use list_rules only when you need the RULE INVENTORY.',
-            '',
-            "Don't use to count traces or evals (that's get_traces). Don't use to deploy a rule (use deploy_rule); don't use to remove one (use delete_rule). Built-in rules are not in the store and cannot be deployed, deleted or disabled — they appear under `built_in` for reference, carrying the criticality this server applies.",
-            '',
-            'Parameters. eval_type filter is exact-match against each rule\'s evalType field (no wildcards). enabled_only excludes rules that are deployed-but-disabled — a rule is disabled without deleting it via delete_rule with `enabled: false` (and re-enabled with `enabled: true`), or from the dashboard; disabled rules stay in the store with their history but do not fire. Both filters are AND-combined when both are set. Both are optional; with no filter, all rules return. Defaults: eval_type=undefined (no filter), enabled_only=false (returns all rules including disabled).',
-            '',
-            "Error modes. Returns empty list if the rule store file doesn't exist (first run). Returns 429 if HTTP rate limit exceeded. Never throws on valid input.",
-        ].join('\n'),
+        title: 'List Rules',
+        description: describeTool({
+            summary: 'The rule inventory: the built-in roster with what each rule needs, the criticality this server applies and its published accuracy, plus every deployed custom rule.',
+            does: 'Read-only, no network. built_in is the shipped roster and is never narrowed by the filters. For each rule: kind (measurement, detection, inference, judgment, policy, verification), mechanism, needs (the inputs it reads — absent means the rule skips, never passes), question, classes, version, weight, ' +
+                'the EFFECTIVE critical flag with criticalSource (default, or config when eval.criticalRules / eval.nonCriticalRules changed it on this server — read it before trusting a passed: true), ' +
+                'and proof: precision and recall with 95% intervals and the positive predictive value at four prevalences, the numbers published at https://iris-eval.com/proof. ' +
+                'rules is the custom-rule store, filterable by eval_type and enabled_only; total and enabled_count count custom rules. quarantined lists store entries this version could not validate; they do not fire.',
+            whenNot: 'To count traces (get_traces). To add, remove or pause a rule (deploy_rule, delete_rule). Built-in rules are not in the store and cannot be deployed, deleted or disabled.',
+            returns: listRulesOutputSchema,
+            errors: 'IRIS_INTERNAL_ERROR if the store file cannot be read. A missing store file is an empty list, not an error. ' +
+                ERROR_ENVELOPE_SENTENCE,
+            siblings: {
+                deploy_rule: 'add a custom rule',
+                delete_rule: 'remove, disable or re-enable one',
+                evaluate_output: 'run the rules',
+            },
+        }),
         inputSchema: strictInput(inputSchema),
+        outputSchema: listRulesOutputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async (args) => {
+    }, guarded(async (args) => {
         // OSS: MCP tools operate under LOCAL_TENANT. Cloud multi-tenant
         // exposure is a v0.5 architectural item (MCP SDK doesn't pass
         // session/tenant context to tool handlers).
@@ -75,19 +82,9 @@ export function registerListRulesTool(server, customRuleStore, evalEngine) {
          * purpose — the filters describe the custom-rule store.
          */
         const built_in = builtInRuleRoster((rule) => evalEngine.effectiveCriticality(rule)).map((r) => ({
-            name: r.name,
-            category: r.category,
-            weight: r.weight,
-            critical: r.critical,
-            criticalSource: r.criticalSource,
+            ...r,
+            proof: ruleProof(r.name),
         }));
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({ rules, total, enabled_count, built_in }),
-                },
-            ],
-        };
-    });
+        return respond(listRulesOutputSchema, { rules, total, enabled_count, built_in, quarantined: customRuleStore.quarantined(LOCAL_TENANT) }, [{ uri: PROOF_RESOURCE_URI, name: 'proof', description: 'The published accuracy of every measured rule, with the corpus it was measured on' }]);
+    }));
 }

package/dist/tools/log-trace.d.ts

@@ -58,4 +58,8 @@ export declare const logTraceInputShape: {
     }, z.core.$strip>>>;
     timestamp: z.ZodOptional<z.ZodString>;
 };
+export declare const logTraceOutputSchema: z.ZodObject<{
+    trace_id: z.ZodString;
+    status: z.ZodLiteral<"stored">;
+}, z.core.$loose>;
 export declare function registerLogTraceTool(server: McpServer, storage: IStorageAdapter): void;

package/dist/tools/log-trace.js

@@ -3,6 +3,9 @@ import { generateTraceId, generateSpanId } from '../utils/ids.js';
 import { LOCAL_TENANT } from '../types/tenant.js';
 import { bestEffortExport } from '../otel/lazy.js';
 import { strictInput, strictNested } from './strict-input.js';
+import { describeTool, ERROR_ENVELOPE_SENTENCE } from './describe.js';
+import { guarded, respond } from './respond.js';
+import { traceUri } from '../resources/uris.js';
 /*
  * The tool-call record — one entry of `tool_calls[]`.
  *
@@ -58,47 +61,51 @@ export const logTraceInputShape = {
     framework: z.string().optional().describe('Agent framework identifier (e.g., langchain, autogen, custom)'),
     input: z.string().optional().describe('Agent input text — the user prompt or upstream input that produced this output'),
     output: z.string().optional().describe('Agent output text — what the agent produced (pass to evaluate_output for scoring)'),
-    tool_calls: z.array(toolCallSchema).optional().describe('Tool calls made during execution (per-call latency, errors, input/output)'),
+    tool_calls: z.array(toolCallSchema).optional().describe('Tool calls made during execution, in order, each { tool_name, input?, output?, latency_ms?, error? } — what the trajectory rules judge; evaluate_output reuses them when given this trace_id'),
     latency_ms: z.number().optional().describe('Total execution time in milliseconds (end-to-end agent latency)'),
     token_usage: TokenUsageSchema.optional().describe('Token usage breakdown (prompt/completion/total — used for cost analysis)'),
     cost_usd: z.number().optional().describe('Total cost in USD — overrides per-span aggregation when provided (treated as authoritative)'),
     metadata: z.record(z.string(), z.unknown()).optional().describe('Opaque key-value tags (e.g. {requestId, userId, env}) — queryable in dashboard, not via get_traces filters'),
-    spans: z.array(SpanSchema).optional().describe('Detailed execution spans (hierarchical span tree with timings, attributes, events)'),
+    spans: z.array(SpanSchema).optional().describe('Detailed execution spans (hierarchical span tree with timings, attributes, events); a span without start_time takes the trace timestamp'),
     timestamp: z.string().optional().describe('Trace timestamp (ISO 8601); defaults to now() when omitted'),
 };
+export const logTraceOutputSchema = z.looseObject({
+    trace_id: z.string().describe('the stored trace id, 32 hex — pass it to evaluate_output, get_traces or delete_trace'),
+    status: z.literal('stored').describe('always "stored" on success'),
+});
 export function registerLogTraceTool(server, storage) {
     server.registerTool('log_trace', {
         title: 'Log Trace',
-        description: [
-            'Persist a single agent execution trace (input, output, spans, tool calls, cost, latency, token usage).',
-            '',
-            'Sibling tools — evaluate_output runs heuristic scoring on the trace; evaluate_with_llm_judge runs semantic LLM-based scoring; verify_citations checks citation grounding; get_traces queries stored traces; delete_trace removes a single trace; list_rules / deploy_rule / delete_rule manage custom evaluation rules. log_trace is the WRITE path that records executions; everything else reads, scores, or manages around it.',
-            '',
-            'Behavior. Writes one row to Iris storage (SQLite by default; Postgres in Cloud tier). When IRIS_OTEL_ENDPOINT is set, ALSO fires a best-effort async export to the configured OTLP/HTTP collector (Jaeger, Tempo, Datadog OTLP, OTEL Collector). The OTel export is fire-and-forget — its success does not affect the tool response; failures are logged but the trace is still stored locally. No authentication in stdio mode. HTTP mode requires a Bearer token ONLY when --api-key / IRIS_API_KEY is set (recommended); with no key configured the auth middleware is a pass-through and writes are unauthenticated — a default HTTP server is protected by its loopback bind (127.0.0.1) and Origin validation, not by a credential. Rate-limited to 20 req/min on HTTP MCP, unlimited on stdio. Not idempotent: each call mints a fresh trace_id, so resubmitting the same payload creates a duplicate trace.',
-            '',
-            'Output shape. Returns a JSON string: `{ "trace_id": "<32-hex>", "status": "stored" }`. The trace_id is the key you pass to evaluate_output or get_traces afterwards.',
-            '',
-            'Use when you want to record an agent execution for later evaluation, analysis, or audit. Call it AFTER the agent has produced output; call evaluate_output afterwards to score it; call get_traces to query historical traces. Store rich context: spans (span tree), tool_calls (which tools were invoked with latency/errors), token_usage, cost_usd, metadata (arbitrary key-value). All optional except agent_name.',
-            '',
-            'Don\'t use when you only need a transient log (use console logging). Don\'t use to update an existing trace — there is no update path in v0.4 (traces are immutable once stored).',
-            '',
-            'Parameters. agent_name is required; everything else is optional. token_usage and cost_usd are summary fields — if you ALSO pass spans with per-tool-call costs, the summary fields are treated as authoritative (no auto-aggregation). spans without an explicit start_time fall back to the trace timestamp; spans with an end_time get a duration_ms derived. metadata is opaque key-value (queryable in the dashboard, not via get_traces filters). tool_calls record per-tool latency + errors; missing latency_ms means "not reported," not "zero." Defaults: span.kind="INTERNAL", span.status_code="UNSET", timestamp=now() if omitted.',
-            '',
-            'Error modes. Throws on missing agent_name. Throws on malformed span or tool_call objects (Zod rejects). Returns 500 on storage failure (disk full, DB locked). Never blocks on the agent — returns within ~50ms for typical payloads.',
-        ].join('\n'),
+        description: describeTool({
+            summary: 'Store one agent execution — input, output, tool calls, spans, cost, latency, token usage — and get the trace_id every later call keys on.',
+            does: 'Writes one trace row to local SQLite and mints a fresh trace_id; nothing is deduplicated, so resubmitting the same payload stores a second trace. ' +
+                'Only agent_name is required. Store what you have: tool_calls so the trajectory rules can later judge what the agent did, cost_usd and token_usage so the cost rules can, input and output so everything else can. ' +
+                'When IRIS_OTEL_ENDPOINT is set the trace is also exported to that collector, best-effort and asynchronous; the local write never waits on it. ' +
+                'Traces are immutable: there is no update path. In stdio mode nothing authenticates the caller; over HTTP a Bearer token is required only when an API key is configured.',
+            whenNot: 'For a transient log line (use your logger). To score an output: log first, then call evaluate_output with the trace_id, which also lets it reuse the stored tool_calls. To change a stored trace: delete_trace and log again.',
+            returns: logTraceOutputSchema,
+            errors: 'IRIS_STORAGE_ERROR when the database cannot be written. An unknown argument or a malformed span or tool_calls entry is refused before the handler runs, naming the valid keys. ' +
+                ERROR_ENVELOPE_SENTENCE,
+            siblings: {
+                evaluate_output: 'score the stored output',
+                get_traces: 'query what was logged',
+                delete_trace: 'remove one trace',
+            },
+        }),
         // Strict at the MCP boundary (unknown args rejected, not stripped).
         // The dashboard's HTTP ingest builds its own — equally strict —
         // schema FROM this shape (dashboard/validation.ts): a client-supplied
         // trace_id is rejected there with a 400 whose message says the server
         // mints it, exactly as this tool mints its own in the handler below.
         inputSchema: strictInput(logTraceInputShape),
+        outputSchema: logTraceOutputSchema,
         annotations: {
             readOnlyHint: false, // Writes a row to storage
             destructiveHint: false, // Creates new data; doesn't overwrite or delete
             idempotentHint: false, // Each call mints a fresh trace_id; duplicate payloads produce distinct traces
             openWorldHint: false, // Local storage first. When IRIS_OTEL_ENDPOINT is set a best-effort async OTel export runs but is non-blocking (tool succeeds even if export fails).
         },
-    }, async (args) => {
+    }, guarded(async (args) => {
         const traceId = generateTraceId();
         const timestamp = args.timestamp ?? new Date().toISOString();
         const trace = {
@@ -128,13 +135,8 @@ export function registerLogTraceTool(server, storage) {
             // eslint-disable-next-line no-console
             console.warn(`[iris.otel] ${err.message}`);
         });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({ trace_id: traceId, status: 'stored' }),
-                },
-            ],
-        };
-    });
+        return respond(logTraceOutputSchema, { trace_id: traceId, status: 'stored' }, [
+            { uri: traceUri(traceId), name: `trace ${traceId}`, description: 'The stored trace with its spans and, later, its evaluations' },
+        ]);
+    }));
 }

package/dist/tools/respond.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { IrisError } from './errors.js';
+export declare const CAPABILITIES_URI = "iris://capabilities";
+export interface ResourceLink {
+    uri: string;
+    name: string;
+    description?: string;
+}
+export declare const CAPABILITIES_LINK: ResourceLink;
+export declare function respond<S extends z.ZodType>(schema: S, payload: object, links?: ResourceLink[]): CallToolResult;
+export declare const errorEnvelopeSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            IRIS_INVALID_ARGUMENT: "IRIS_INVALID_ARGUMENT";
+            IRIS_UNKNOWN_TRACE: "IRIS_UNKNOWN_TRACE";
+            IRIS_DUPLICATE_RULE: "IRIS_DUPLICATE_RULE";
+            IRIS_INVALID_RULE_CONFIG: "IRIS_INVALID_RULE_CONFIG";
+            IRIS_JUDGE_NOT_ENABLED: "IRIS_JUDGE_NOT_ENABLED";
+            IRIS_JUDGE_UNKNOWN_MODEL: "IRIS_JUDGE_UNKNOWN_MODEL";
+            IRIS_BUDGET_EXCEEDED: "IRIS_BUDGET_EXCEEDED";
+            IRIS_PROVIDER_ERROR: "IRIS_PROVIDER_ERROR";
+            IRIS_JUDGE_FAILED: "IRIS_JUDGE_FAILED";
+            IRIS_STORAGE_ERROR: "IRIS_STORAGE_ERROR";
+            IRIS_INTERNAL_ERROR: "IRIS_INTERNAL_ERROR";
+        }>;
+        message: z.ZodString;
+        recovery: z.ZodArray<z.ZodString>;
+        retryable: z.ZodBoolean;
+        field: z.ZodOptional<z.ZodString>;
+        valid: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        see: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodString>;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type ErrorEnvelope = z.infer<typeof errorEnvelopeSchema>;
+export declare function errorResult(err: IrisError): CallToolResult;
+/** Wrap a handler so every failure returns an envelope instead of a flattened line. */
+export declare function guarded<A extends unknown[]>(fn: (...args: A) => Promise<CallToolResult> | CallToolResult): (...args: A) => Promise<CallToolResult>;
+/** Links for what an evaluation created: the evaluation, and the trace when linked. */
+export declare function evaluationLinks(evalId: string, traceId?: string): ResourceLink[];

package/dist/tools/respond.js

@@ -0,0 +1,90 @@
+/*
+ * One way to answer a tool call.
+ *
+ * `respond` parses the payload through the tool's own output schema
+ * BEFORE serialising it — a field the schema does not describe fails a
+ * test, not a user — and emits the same object twice: as the text a
+ * client without structured-content support reads, and as
+ * `structuredContent` for one that has it. Beside the payload go
+ * `resource_link` items for what the call created and what explains its
+ * limits, so a client can follow them with resources/read instead of
+ * guessing a URI.
+ *
+ * `errorResult` is the failure shape: the IrisError envelope as the text
+ * and as structuredContent, `isError: true`, and a link to
+ * iris://capabilities. `guarded` wraps a handler so nothing thrown inside
+ * it reaches the SDK's flattener.
+ */
+import { z } from 'zod';
+import { ERROR_CODE_CATALOGUE, toIrisError } from './errors.js';
+import { CAPABILITIES_RESOURCE_URI, evaluationUri, traceUri } from '../resources/uris.js';
+export const CAPABILITIES_URI = CAPABILITIES_RESOURCE_URI;
+export const CAPABILITIES_LINK = {
+    uri: CAPABILITIES_URI,
+    name: 'capabilities',
+    description: 'What this server can judge, what each rule needs, judge state, limits, tools and resources',
+};
+const linkItem = (l) => ({
+    type: 'resource_link',
+    uri: l.uri,
+    name: l.name,
+    ...(l.description ? { description: l.description } : {}),
+    mimeType: 'application/json',
+});
+/** JSON round-trip: what the text carries is exactly what structuredContent carries. */
+function normalise(payload) {
+    return JSON.parse(JSON.stringify(payload));
+}
+export function respond(schema, payload, links = []) {
+    const body = normalise(payload);
+    const parsed = schema.safeParse(body);
+    if (!parsed.success) {
+        // A programming error: the tool built a response its own schema does
+        // not describe. Loud on purpose — the drift-lock tests catch it.
+        const issues = parsed.error.issues.slice(0, 3).map((i) => `${i.path.map(String).join('.') || '(root)'}: ${i.message}`);
+        throw new Error(`response does not match the tool's output schema: ${issues.join('; ')}`);
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }, ...links.map(linkItem)],
+        structuredContent: body,
+    };
+}
+export const errorEnvelopeSchema = z.looseObject({
+    error: z.looseObject({
+        code: z.enum(ERROR_CODE_CATALOGUE),
+        message: z.string(),
+        recovery: z.array(z.string()),
+        retryable: z.boolean(),
+        field: z.string().optional(),
+        valid: z.array(z.string()).optional(),
+        see: z.string().optional(),
+        kind: z.string().optional(),
+        retryAfterMs: z.number().optional(),
+    }),
+});
+export function errorResult(err) {
+    const body = normalise({ error: err.envelope });
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }, linkItem(CAPABILITIES_LINK)],
+        structuredContent: body,
+        isError: true,
+    };
+}
+/** Wrap a handler so every failure returns an envelope instead of a flattened line. */
+export function guarded(fn) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (err) {
+            return errorResult(toIrisError(err));
+        }
+    };
+}
+/** Links for what an evaluation created: the evaluation, and the trace when linked. */
+export function evaluationLinks(evalId, traceId) {
+    const links = [{ uri: evaluationUri(evalId), name: `evaluation ${evalId}`, description: 'The stored evaluation, as every reader sees it' }];
+    if (traceId)
+        links.push({ uri: traceUri(traceId), name: `trace ${traceId}`, description: 'The trace this evaluation is linked to, with its spans and every evaluation' });
+    return links;
+}

package/dist/tools/strict-input.js

@@ -29,7 +29,7 @@ export function strictInput(shape) {
                 `Valid arguments: ${validKeys}. ` +
                 'Unknown arguments are rejected rather than silently ignored, so a misspelled ' +
                 'argument name cannot change what gets evaluated — check the spelling against ' +
-                "the tool's input schema and retry."
+                "the tool's input schema and retry. Code IRIS_INVALID_ARGUMENT."
             : undefined,
     });
 }

package/dist/tools/trace-link.d.ts

@@ -11,6 +11,8 @@ export declare function unknownTraceMessage(traceId: string): string;
  * existence check had to load the row anyway. Fetching it twice would be
  * two reads for one fact — and two chances for them to disagree.
  */
+/** The IRIS_UNKNOWN_TRACE error, built once for both the pre-check and the insert race. */
+export declare function unknownTraceError(traceId: string): import("./errors.js").IrisError;
 export declare function getTraceOrThrow(storage: IStorageAdapter, tenantId: TenantId, traceId: string): Promise<Trace>;
 export declare function assertTraceExists(storage: IStorageAdapter, tenantId: TenantId, traceId: string): Promise<void>;
 /** insertEvalResult with the foreign-key race translated into the same clear message. */

package/dist/tools/trace-link.js

@@ -1,3 +1,4 @@
+import { irisError } from './errors.js';
 /*
  * Linking an evaluation to a trace that does not exist.
  *
@@ -26,10 +27,20 @@ export function unknownTraceMessage(traceId) {
  * existence check had to load the row anyway. Fetching it twice would be
  * two reads for one fact — and two chances for them to disagree.
  */
+/** The IRIS_UNKNOWN_TRACE error, built once for both the pre-check and the insert race. */
+export function unknownTraceError(traceId) {
+    return irisError('IRIS_UNKNOWN_TRACE', unknownTraceMessage(traceId), {
+        field: 'trace_id',
+        recovery: [
+            'Pass the trace_id that log_trace returned, or one listed by get_traces.',
+            'Or omit trace_id to store an unlinked evaluation.',
+        ],
+    });
+}
 export async function getTraceOrThrow(storage, tenantId, traceId) {
     const trace = await storage.getTrace(tenantId, traceId);
     if (!trace)
-        throw new Error(unknownTraceMessage(traceId));
+        throw unknownTraceError(traceId);
     return trace;
 }
 export async function assertTraceExists(storage, tenantId, traceId) {
@@ -44,7 +55,7 @@ export async function insertLinkedEvalResult(storage, tenantId, result) {
         const code = err.code;
         const message = err instanceof Error ? err.message : String(err);
         if (result.trace_id && (code === 'SQLITE_CONSTRAINT_FOREIGNKEY' || /FOREIGN KEY constraint failed/i.test(message))) {
-            throw new Error(unknownTraceMessage(result.trace_id));
+            throw unknownTraceError(result.trace_id);
         }
         throw err;
     }

package/dist/tools/verify-citations.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IStorageAdapter } from '../types/query.js';
 /**
@@ -5,8 +6,8 @@ import type { IStorageAdapter } from '../types/query.js';
  * was nothing to judge (no citations, none resolved). It is NOT the honest
  * answer when citations resolved and the judge then failed on every one —
  * a wrong API key, a model the provider refused, a parse failure — because
- * the caller reads "passed" and ships. That case is an error naming the
- * cause; nothing is stored. (v0.6.0 acceptance pass, observation 3.)
+ * the caller reads "passed" and ships. That case is IRIS_JUDGE_FAILED
+ * naming the cause; nothing is stored. (v0.6.0 acceptance pass, observation 3.)
  */
 export declare function assertJudgeRan(result: {
     totalResolved: number;
@@ -19,4 +20,18 @@ export declare function assertJudgeRan(result: {
         };
     }>;
 }): void;
+export declare const verifyCitationsOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    trace_id: z.ZodOptional<z.ZodString>;
+    overall_score: z.ZodNullable<z.ZodNumber>;
+    passed: z.ZodBoolean;
+    total_citations_found: z.ZodNumber;
+    total_resolved: z.ZodNumber;
+    total_judged: z.ZodNumber;
+    total_supported: z.ZodNumber;
+    total_cost_usd: z.ZodNumber;
+    citations: z.ZodArray<z.ZodObject<{
+        resolve_status: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
 export declare function registerVerifyCitationsTool(server: McpServer, storage: IStorageAdapter): void;