hoi4-agent-tools 3.10.0 → 4.0.0

package/dist/hoi4_agent_tools/mcp/server/argument-errors.js

@@ -0,0 +1,72 @@
+import { errorResult } from '../../core/operation-result.js';
+import { ServiceError } from '../../core/result.js';
+/**
+ * Invalid arguments come back as a tool error naming each wrong field, what it expected and a
+ * working call, not as a protocol error: clients show a tool error's text to the model, while
+ * some reduce a protocol error to a generic "Invalid tool arguments".
+ */
+export const ARGUMENT_EXAMPLES = {
+    'hoi4.reference_context': '{"surface":"event"}',
+    'hoi4.reference_search': '{"query":"add_timed_idea"}',
+    'hoi4.reference_read': '{"id":"<id of a reference_search result>","revision":"<revision of the same result>"}',
+    'hoi4.source_lookup': '{"symbol":"my_scripted_effect"} or {"path":"events/my_events.txt","line":42}',
+    'hoi4.script_validate': '{"path":"events/my_events.txt"} or {"source":"add_political_power = 10","kind":"effect","scope":"country"}',
+    'hoi4.error_log': '{"scope":"mod","category":"effect"}',
+    'hoi4.mod_index': '{"mode":"overview"} or {"mode":"next_id","kind":"event","namespace":"my_mod"}',
+    'hoi4.event_inspect': '{"mode":"lint","selector":"chaosx.nr14"} or {"mode":"trace","selector":"chaosx.nr14.1","direction":"downstream"}',
+    'hoi4.event_render': '{"view":"overview","selector":"chaosx.nr14"}',
+    'hoi4.focus_inspect': '{"treeId":"my_focus_tree"}',
+    'hoi4.focus_render': '{"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree"}',
+    'hoi4.focus_rewrite': '{"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}',
+    'hoi4.gui_inspect': '{"windowName":"my_window"}',
+    'hoi4.gui_render': '{"windowName":"my_window","scenario":{"id":"normal"}}',
+    'hoi4.gui_rewrite': '{"mode":"patches","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"expectedSourceHash":"<sha256 of the file>","patches":[{"start":120,"end":130,"expectedText":"x = 10 y","text":"x = 40 y"}]}',
+    'hoi4.map_inspect': '{"query":"Brandenburg","lookupOnly":true} or {"layer":"state","tile":{"x":2600,"y":500,"width":256,"height":256}}',
+    'hoi4.map_rewrite': '{"operations":[{"id":"new-state","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}',
+    'hoi4.tech_inspect': '{"mode":"scan"} or {"mode":"explain","technologyId":"my_tech"} or {"mode":"lint"}',
+    'hoi4.tech_render': '{"view":"folder","folderId":"my_folder"}',
+    'hoi4.probability_inspect': '{"candidatePool":["my_decision"]} or {"source":"events/my_events.txt","adapter":"event_option_ai_chance"}',
+    'hoi4.probability_analyze': '{"analysis":"sweep","source":"common/decisions/my_decisions.txt","candidatePool":["my_decision"],"scenarioSet":[{"actor":"GER","state":{"variable.pressure":10}}],"sweep":{"paths":["variable.pressure"],"steps":10}}',
+    'hoi4.impact_inspect': '{"symbols":[{"kind":"scripted_effect","id":"my_effect"}]} or {"changedFiles":["mod:common/scripted_effects/my_effects.txt"]}',
+    'hoi4.decision_inspect': '{"mode":"inventory"} or {"mode":"inspect","id":"my_decision","scenarios":[{"id":"base","actor":"GER","state":{}}]}',
+    'hoi4.mechanic_test': '{"test":{"id":"my_test","scenario":{"schemaVersion":"1.0","id":"my_test","state":{"treasury":10,"savings":2}},"steps":[{"kind":"effect","source":{"kind":"scripted_effect","id":"my_effect"}}],"assertions":[{"id":"kept","kind":"conservation","paths":[{"key":"treasury"},{"key":"savings"}]}]}}',
+    'hoi4.package_check': '{"manifest":{"schemaVersion":"1.0","id":"my_package","definitions":[{"kind":"scripted_effect","id":"my_effect"}]}}',
+    'hoi4.scenario_test': '{"suitePath":"tests/my_suite.json","maxCases":20}',
+    'hoi4.job_inspect': '{"jobId":"job_<64 hex characters from a native task id>"}',
+    'hoi4.job_cancel': '{"jobId":"job_<64 hex characters from a native task id>"}',
+};
+function describeIssue(issue) {
+    const field = issue.path.length === 0 ? '(arguments)' : issue.path.map(String).join('.');
+    let problem = issue.message;
+    if (issue.code === 'unrecognized_keys')
+        problem = `unknown field${issue.keys.length === 1 ? '' : 's'} ${issue.keys.join(', ')}`;
+    else if (issue.code === 'invalid_value')
+        problem = `expected one of ${issue.values.map((value) => JSON.stringify(value)).join(', ')}`;
+    else if (issue.code === 'invalid_union') {
+        // Name the alternative that came closest: the one with the fewest problems.
+        const closest = [...issue.errors].sort((left, right) => left.length - right.length)[0];
+        const first = closest?.[0];
+        if (first !== undefined) {
+            const nested = describeIssue(first);
+            problem = `${issue.message}; closest form: ${nested.field === '(arguments)' ? '' : `${nested.field}: `}${nested.problem}`;
+        }
+    }
+    return { field, problem: problem.slice(0, 300) };
+}
+export function invalidArgumentsError(toolName, error) {
+    const issues = error.issues.slice(0, 6).map(describeIssue);
+    const example = ARGUMENT_EXAMPLES[toolName];
+    const message = [
+        `Invalid arguments for ${toolName}: ${issues.map(({ field, problem }) => `${field}: ${problem}`).join('; ')}.`,
+        ...(example === undefined ? [] : [`Example: ${example}.`]),
+        'The tool input schema lists every accepted field.',
+    ].join(' ');
+    return new ServiceError('INVALID_ARGUMENTS', message.slice(0, 1_500), {
+        tool: toolName,
+        issues,
+        ...(example === undefined ? {} : { example }),
+    });
+}
+export function invalidArgumentsResult(toolName, error, workspaceId) {
+    return errorResult(invalidArgumentsError(toolName, error), typeof workspaceId === 'string' ? workspaceId : 'current');
+}

package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js

@@ -1,9 +1,12 @@
 import { fileURLToPath } from 'node:url';
+import { normalizeToolArguments } from '../../schemas/lenient-arguments.js';
+import { invalidArgumentsResult } from './argument-errors.js';
+import { slimListedTool } from './tool-listing.js';
 import { CallToolResultSchema, ClientCapabilitiesSchema, ListToolsResultSchema, } from '@modelcontextprotocol/core';
 import { CLIENT_CAPABILITIES_META_KEY, inputRequired, ProtocolError, ProtocolErrorCode, } from '@modelcontextprotocol/server';
 import { z } from 'zod/v4';
 import { isJobControlTool, JobControlService } from '../../core/job-controls.js';
-import { OperationTaskService } from '../../core/operation-tasks.js';
+import { OperationTaskService, releaseIdleWorkers } from '../../core/operation-tasks.js';
 import { errorResult } from '../../core/operation-result.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../../version.js';
 import { MODERN_TASK_ROUTES, ModernTaskRoutingServer } from '../transports/modern-task-routing.js';
@@ -62,10 +65,16 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
         },
         instructions: SERVER_INSTRUCTIONS,
     });
+    // Warm job workers outlive single calls, not the client session that used them.
+    const previousOnClose = server.onclose;
+    server.onclose = () => {
+        previousOnClose?.();
+        void releaseIdleWorkers(engine);
+    };
     registerModernResources(server, engine, context);
     registerModernPrompts(server);
     server.setRequestHandler('tools/list', () => ListToolsResultSchema.parse({
-        tools: definitions.map(({ name, inputSchema, outputSchema, ...metadata }) => ({
+        tools: definitions.map(({ name, inputSchema, outputSchema, ...metadata }) => slimListedTool({
             ...metadata,
             name,
             inputSchema: {
@@ -86,9 +95,18 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
         const definition = definitions.find(({ name }) => name === request.params.name);
         if (definition === undefined)
             throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Unknown tool');
-        const input = definition.inputSchema.safeParse(request.params.arguments ?? {});
-        if (!input.success)
-            throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Invalid tool arguments');
+        const input = definition.inputSchema.safeParse(normalizeToolArguments(definition.name, request.params.arguments ?? {}));
+        if (!input.success) {
+            // A tool error, not a protocol error, so the model sees which field to correct.
+            const workspaceId = request.params.arguments
+                ?.workspaceId;
+            return CallToolResultSchema.parse({
+                ...invalidArgumentsResult(definition.name, input.error, workspaceId),
+                resultType: 'complete',
+                ttlMs: 0,
+                cacheScope: 'private',
+            });
+        }
         const capabilities = clientCapabilities(extra.mcpReq.envelope);
         const arguments_ = z.record(z.string(), z.json()).parse(input.data);
         let operationContext = context;

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -14,6 +14,7 @@ import { registerMcpResources } from '../resources/register.js';
 import { installRequestLifecycle } from './request-lifecycle.js';
 import { PersistentJobTaskStore } from './job-task-store.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
+import { releaseIdleWorkers } from '../../core/operation-tasks.js';
 export { SERVER_INSTRUCTIONS } from './instructions.js';
 export function createMcpServer(engine, context = {}) {
     let serverContext = context;
@@ -31,6 +32,12 @@ export function createMcpServer(engine, context = {}) {
         taskStore,
     });
     installRequestLifecycle(server, engine);
+    // Warm job workers outlive single calls, not the client session that used them.
+    const previousOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        previousOnClose?.();
+        void releaseIdleWorkers(engine);
+    };
     serverContext = {
         ...context,
         resolveCurrentWorkspaceId: async (signal) => {

package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js

@@ -1,47 +1,41 @@
 import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { DOMAIN_TOOL_NAMES } from '../../core/domain-tools.js';
+import { normalizeToolArguments } from '../../schemas/lenient-arguments.js';
+import { referenceTools } from '../tools/reference.js';
+import { jobControlTools } from '../tools/job.js';
+import { invalidArgumentsResult } from './argument-errors.js';
+import { taskToolCatalog } from './task-tool-catalog.js';
 import { progressReporter, withProgressHeartbeat } from './progress.js';
 import { withTaskRequestSignal } from './task-request-context.js';
+import { slimToolList } from './tool-listing.js';
 // Durable task compatibility and cancellation are control traffic. They must
 // remain responsive while every domain-execution slot is occupied.
 const controlTools = new Set(['hoi4.job_inspect', 'hoi4.job_cancel']);
-const backgroundTools = new Set([
-    'hoi4.impact_inspect',
-    'hoi4.decision_inspect',
-    'hoi4.mechanic_test',
-    'hoi4.package_check',
-    'hoi4.scenario_test',
-    'hoi4.event_inspect',
-    'hoi4.event_render',
-    'hoi4.event_compare',
-    'hoi4.tech_inspect',
-    'hoi4.tech_render',
-    'hoi4.tech_compare',
-    'hoi4.probability_inspect',
-    'hoi4.probability_evaluate',
-    'hoi4.probability_sweep',
-    'hoi4.probability_simulate',
-    'hoi4.probability_sequence',
-    'hoi4.probability_compare',
-    'hoi4.probability_render',
-    'hoi4.map_inspect',
-    'hoi4.map_render',
-    'hoi4.map_rewrite',
-    'hoi4.gui_inspect',
-    'hoi4.gui_render',
-    'hoi4.gui_rewrite',
-    'hoi4.focus_inspect',
-    'hoi4.focus_render',
-    'hoi4.focus_raster',
-    'hoi4.focus_rewrite',
-]);
+const backgroundTools = new Set(DOMAIN_TOOL_NAMES);
+let inputSchemas;
+function inputSchema(name) {
+    inputSchemas ??= new Map([...taskToolCatalog, ...referenceTools, ...jobControlTools].map(({ name: toolName, inputSchema: schema }) => [toolName, schema]));
+    return inputSchemas.get(name);
+}
 /** Wrap the public SDK handler registration so optional tools receive the same lifecycle. */
 export function installRequestLifecycle(server, engine) {
     const register = server.server.setRequestHandler.bind(server.server);
     const owner = {};
     server.server.setRequestHandler = (schema, handler) => {
         register(schema, (request, extra) => {
+            if (request.method === 'tools/list')
+                return Promise.resolve(handler(request, extra)).then(slimToolList);
             if (request.method !== 'tools/call')
                 return handler(request, extra);
+            const params = request.params;
+            if (params !== undefined && typeof params.name === 'string') {
+                params.arguments = normalizeToolArguments(params.name, params.arguments);
+                // Answer invalid arguments with a tool error that names the fields and a working call.
+                const schema = params.task === undefined ? inputSchema(params.name) : undefined;
+                const parsed = schema?.safeParse(params.arguments ?? {});
+                if (parsed !== undefined && !parsed.success)
+                    return Promise.resolve(invalidArgumentsResult(params.name, parsed.error, params.arguments?.workspaceId));
+            }
             const progress = progressReporter(extra);
             const taskCall = CallToolRequestSchema.safeParse(request);
             if (taskCall.success && controlTools.has(taskCall.data.params.name))

package/dist/hoi4_agent_tools/mcp/server/tool-listing.js

@@ -0,0 +1,45 @@
+/**
+ * Every tool schema is sent to the client's model on each session, so listed schemas carry no
+ * bytes that change nothing: the per-schema `$schema` dialect declaration (the schemas use no
+ * dialect-specific keywords, so the MCP default dialect reads them identically) and the
+ * safe-integer bounds that every unbounded integer receives.
+ */
+const SAFE_INTEGER_BOUNDS = new Map([
+    ['maximum', Number.MAX_SAFE_INTEGER],
+    ['minimum', Number.MIN_SAFE_INTEGER],
+]);
+function slimSchema(value) {
+    if (Array.isArray(value))
+        return value.map(slimSchema);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (key === '$schema')
+            continue;
+        if (SAFE_INTEGER_BOUNDS.get(key) === child)
+            continue;
+        result[key] = slimSchema(child);
+    }
+    return result;
+}
+/** Remove redundant schema bytes from one listed tool, leaving everything else untouched. */
+export function slimListedTool(tool) {
+    return {
+        ...tool,
+        ...(tool.inputSchema === undefined ? {} : { inputSchema: slimSchema(tool.inputSchema) }),
+        ...(tool.outputSchema === undefined ? {} : { outputSchema: slimSchema(tool.outputSchema) }),
+    };
+}
+/** Apply {@link slimListedTool} to a `tools/list` result. */
+export function slimToolList(result) {
+    if (result === null || typeof result !== 'object' || !('tools' in result))
+        return result;
+    const { tools } = result;
+    if (!Array.isArray(tools))
+        return result;
+    return {
+        ...result,
+        tools: tools.map((tool) => slimListedTool(tool)),
+    };
+}

package/dist/hoi4_agent_tools/mcp/tools/analysis.js

@@ -36,6 +36,26 @@ const decisionOutputSchema = strictOperationResultSchema(z
     overrides: nonNegativeIntegerSchema,
     scenarios: nonNegativeIntegerSchema,
     unresolvedDefinitions: nonNegativeIntegerSchema,
+    unresolvedSample: z
+        .array(z.object({ id: z.string(), path: z.string(), reason: z.string() }).strict())
+        .max(8)
+        .optional(),
+    outcomes: z
+        .array(z
+        .object({
+        scenarioId: z.string(),
+        found: z.boolean(),
+        eligible: z.string().optional(),
+        visible: z.string().nullable().optional(),
+        available: z.string().optional(),
+        unresolved: z
+            .array(z.object({ code: z.string(), message: z.string() }).strict())
+            .max(5)
+            .optional(),
+    })
+        .strict())
+        .max(16)
+        .optional(),
 })
     .strict());
 const mechanicOutputSchema = strictOperationResultSchema(z
@@ -112,7 +132,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.impact_inspect',
         title: 'Inspect cross-system impact',
-        description: 'Trace definitions and consumers of symbols or changed source across HOI4 systems. Proposed sources are analyzed in memory; full revision-bound evidence is linked.',
+        description: 'Trace where symbols are defined and consumed across focuses, events, decisions, ideas, GUI and helpers, or what a changed file affects; proposed sources are analyzed in memory. Example: {"symbols":[{"kind":"scripted_effect","id":"my_effect"}]}. Returns consumer counts inline; the revision-bound graph is a linked resource.',
         inputSchema: impactInspectRequestSchema,
         outputSchema: impactOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -120,7 +140,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.decision_inspect',
         title: 'Inspect decisions and missions',
-        description: 'Inventory decisions or evaluate declared actor and target scenarios for gates, payment, lifecycle, and proposed-source differences. Full evidence is linked.',
+        description: 'Inventory decisions and missions, or evaluate one under declared actor and target scenarios: visibility, availability, payment, lifecycle and proposed-source differences. Example: {"mode":"inspect","id":"my_decision","scenarios":[{"id":"base","actor":"GER","state":{}}]}. Returns each scenario outcome inline; full evidence is linked.',
         inputSchema: decisionInspectRequestSchema,
         outputSchema: decisionOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -128,7 +148,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.mechanic_test',
         title: 'Test declared mechanic steps',
-        description: 'Interpret bounded, source-backed effect steps on isolated declared state and check typed invariants. Unsupported effects remain unresolved; no game or mod source is changed.',
+        description: 'Interpret source-backed effect steps (scripted effect, event option, decision, focus reward) on a declared state and check typed assertions; unsupported effects stay unresolved and no source changes. Example: {"test":{"id":"t","scenario":{"schemaVersion":"1.0","id":"t","state":{"treasury":10}},"steps":[...],"assertions":[...]}}. See docs/mechanics.md.',
         inputSchema: mechanicInputSchema,
         outputSchema: mechanicOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -136,7 +156,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.package_check',
         title: 'Check package connections',
-        description: 'Check a declarative package manifest against active definitions, references, registrations, localisation, assets, and required suite cases.',
+        description: 'Check a declarative package manifest against active definitions, calls, registrations, localisation, assets and required suite cases. Example: {"manifest":{"schemaVersion":"1.0","id":"my_package","definitions":[{"kind":"scripted_effect","id":"my_effect"}]}}. Returns present, absent, shadowed and unresolved counts inline.',
         inputSchema: packageInputSchema,
         outputSchema: packageOutputSchema,
         annotations: readOnlyAnalysisTool,
@@ -144,7 +164,7 @@ export const analysisTaskTools = [
     {
         name: 'hoi4.scenario_test',
         title: 'Run scenario suite',
-        description: 'Run named inline or workspace-relative cases through bounded typed read-only domain services. Large suites return an authenticated continuation.',
+        description: 'Run a suite of named mechanic, package or read-only tool cases, inline or from a workspace file, in resumable revision-bound batches. Example: {"suitePath":"tests/my_suite.json","maxCases":20}. Returns completed, failed, unresolved and pending counts, and a continuation while cases remain.',
         inputSchema: scenarioInputSchema,
         outputSchema: scenarioOutputSchema,
         annotations: readOnlyAnalysisTool,

package/dist/hoi4_agent_tools/mcp/tools/event.js

@@ -1,11 +1,14 @@
 import { registerLegacyTaskTools } from '../server/legacy-task-tools.js';
 import { z } from 'zod/v4';
 import { helperExpansionRequestSchema, helperExpansionSummarySchema, } from '../../schemas/helper-expansion.js';
-import { eventDirectionSchema, eventGraphReferenceSchema, eventImpactSubjectSchema, eventInspectModeSchema, eventProposedSourceSchema, eventRenderViewSchema, eventSelectorSchema, eventInspectRequestSchema, eventRenderRequestSchema, eventCompareRequestSchema, validateEventCompareRequest, validateEventInspectRequest, eventStateSubjectSchema, } from '../../schemas/event.js';
+import { eventDirectionSchema, eventGraphReferenceSchema, eventImpactSubjectSchema, eventInspectModeSchema, eventProposedSourceSchema, eventRenderViewSchema, eventSelectorSchema, eventInspectRequestSchema, eventRenderRequestSchema, validateEventInspectToolRequest, eventStateSubjectSchema, } from '../../schemas/event.js';
 import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
 import { strictOperationResultSchema } from '../server/result.js';
-const nestedSelectorSchema = compactValidatedInputSchema(eventSelectorSchema, 'Event selector; see docs/events.md.');
+// The selector is published in full: it is the field agents most often get wrong. A plain
+// string ("my_ns.12", "my_ns", "events/file.txt") is also accepted and normalized.
+const nestedSelectorSchema = eventSelectorSchema;
+const nestedEndpointSchema = compactValidatedInputSchema(eventSelectorSchema, 'Same shape as selector, or a plain event ID string.');
 const nestedStateSubjectSchema = compactValidatedInputSchema(eventStateSubjectSchema, 'State kind and name.');
 const nestedImpactSubjectSchema = compactValidatedInputSchema(eventImpactSubjectSchema, 'Impact kind and name.');
 const nestedGraphReferenceSchema = compactValidatedInputSchema(eventGraphReferenceSchema, 'Cached revision or graph artifact URI.');
@@ -14,30 +17,23 @@ const eventInspectInputSchema = z
     .object({
     ...eventInspectRequestSchema.shape,
     selector: nestedSelectorSchema.optional(),
-    from: nestedSelectorSchema.optional(),
-    to: nestedSelectorSchema.optional(),
+    from: nestedEndpointSchema.optional(),
+    to: nestedEndpointSchema.optional(),
     stateSubject: nestedStateSubjectSchema.optional(),
     impactSubject: nestedImpactSubjectSchema.optional(),
     helperExpansion: compactValidatedInputSchema(helperExpansionRequestSchema, 'Bounded helper paths; opaque continuationUri resumes the same source and roots. See docs/events.md.').optional(),
+    before: nestedGraphReferenceSchema.optional(),
+    after: nestedGraphReferenceSchema.optional(),
+    proposedSources: z.array(nestedProposedSourceSchema).min(1).max(64).optional(),
 })
     .strict()
-    .superRefine(validateEventInspectRequest);
+    .superRefine(validateEventInspectToolRequest);
 const eventRenderInputSchema = z
     .object({
     ...eventRenderRequestSchema.shape,
     selector: nestedSelectorSchema.optional(),
 })
     .strict();
-const eventCompareInputSchema = z
-    .object({
-    ...eventCompareRequestSchema.shape,
-    selector: nestedSelectorSchema.optional(),
-    before: nestedGraphReferenceSchema.optional(),
-    after: nestedGraphReferenceSchema.optional(),
-    proposedSources: z.array(nestedProposedSourceSchema).min(1).max(64).optional(),
-})
-    .strict()
-    .superRefine(validateEventCompareRequest);
 const eventGraphCountsSchema = z
     .object({
     events: nonNegativeIntegerSchema,
@@ -74,7 +70,7 @@ const renderHashSchema = z
     html: sha256Schema.optional(),
 })
     .strict();
-const eventInspectOutputSchema = strictOperationResultSchema(z
+const eventInspectDataSchema = z
     .object({
     mode: eventInspectModeSchema,
     analysisMode: z.enum(['full', 'focused']),
@@ -84,7 +80,7 @@ const eventInspectOutputSchema = strictOperationResultSchema(z
     helperExpansion: helperExpansionSummarySchema.optional(),
     boundary: inspectBoundarySchema,
 })
-    .strict());
+    .strict();
 const eventRenderOutputSchema = strictOperationResultSchema(z
     .object({
     view: eventRenderViewSchema,
@@ -110,7 +106,7 @@ const eventRenderOutputSchema = strictOperationResultSchema(z
         .strict(),
 })
     .strict());
-const eventCompareOutputSchema = strictOperationResultSchema(z
+const eventCompareDataSchema = z
     .object({
     beforeRevision: sha256Schema,
     afterRevision: sha256Schema,
@@ -161,7 +157,8 @@ const eventCompareOutputSchema = strictOperationResultSchema(z
     })
         .strict(),
 })
-    .strict());
+    .strict();
+const eventInspectOutputSchema = strictOperationResultSchema(z.union([eventInspectDataSchema, eventCompareDataSchema]));
 const readOnlyEventTool = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -172,7 +169,7 @@ export const eventTaskTools = [
     {
         name: 'hoi4.event_inspect',
         title: 'Inspect event chains',
-        description: 'Scan, find roots, trace, explain paths, inspect state flow, lint, or assess impact. Full source-linked reports are resources.',
+        description: 'Scan, find roots, trace, explain paths, inspect state flow, lint, assess impact or compare (mode compare) event graphs. Example: {"mode":"trace","selector":"my_mod.1","direction":"downstream"}; a selector is an event ID, a namespace, my_mod.* or a file. Returns counts and the main findings inline; the full source-linked report is a resource.',
         inputSchema: eventInspectInputSchema,
         outputSchema: eventInspectOutputSchema,
         annotations: readOnlyEventTool,
@@ -180,19 +177,11 @@ export const eventTaskTools = [
     {
         name: 'hoi4.event_render',
         title: 'Render event chains',
-        description: 'Render deterministic JSON, SVG, PNG, and optional HTML for an event-chain view. Complete artifacts retain source links.',
+        description: 'Render a source-linked event view (overview, neighborhood, options, timing, state, scope, unresolved and more) as JSON, SVG and PNG. Example: {"view":"overview","selector":"my_mod"}. Images are linked artifacts; calls that cannot be resolved statically stay explicit unresolved edges.',
         inputSchema: eventRenderInputSchema,
         outputSchema: eventRenderOutputSchema,
         annotations: readOnlyEventTool,
     },
-    {
-        name: 'hoi4.event_compare',
-        title: 'Compare event chains',
-        description: 'Compare cached, artifact-backed, current, or in-memory proposed event graphs, optionally selecting one downstream chain. Full changes and explicit selection coverage are resources.',
-        inputSchema: eventCompareInputSchema,
-        outputSchema: eventCompareOutputSchema,
-        annotations: readOnlyEventTool,
-    },
 ];
 export function registerEventTools(server) {
     registerLegacyTaskTools(server, eventTaskTools);

package/dist/hoi4_agent_tools/mcp/tools/focus.js

@@ -135,23 +135,15 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_inspect',
         title: 'Inspect focus trees',
-        description: 'Inspect focus trees and continuous palettes, including source references, diagnostics, and layout.',
+        description: 'Read national focus trees and continuous-focus palettes: structure, layout, source references and diagnostics. Example: {"treeId":"my_focus_tree"}. Returns counts and the main diagnostics inline; the full report is a linked resource.',
         inputSchema: focusInspectRequestSchema,
         outputSchema: focusInspectOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.focus_render',
-        title: 'Render focus review artifacts',
-        description: 'Render focus HTML, SVG, JSON, and source maps. Use hoi4.focus_raster for decoded icons and PNG.',
-        inputSchema: focusRenderRequestSchema,
-        outputSchema: focusRenderOutputSchema,
-        annotations: artifactProducing,
-    },
-    {
-        name: 'hoi4.focus_raster',
-        title: 'Rasterize focus review artifacts',
-        description: 'Render focus PNG with decoded source icons; also returns HTML, SVG, and JSON.',
+        title: 'Render a focus tree or continuous palette',
+        description: 'Render a focus tree or palette as a PNG with decoded icons plus HTML, SVG and JSON source maps (png:false for vector only; cropFocusIds adds close-ups). Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree"}. Images are linked artifacts, not inline.',
         inputSchema: focusRenderRequestSchema,
         outputSchema: focusRenderOutputSchema,
         annotations: artifactProducing,
@@ -159,7 +151,7 @@ export const focusTaskTools = [
     {
         name: 'hoi4.focus_rewrite',
         title: 'Create or clean up focus content',
-        description: 'Create or compact a focus tree or palette from a complete plan. Use treeId for existing trees and createIfMissing for new files.',
+        description: 'Create a focus tree or palette from a complete plan (createIfMissing), or re-lay out an existing tree without a plan. Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}. Validates, writes atomically and returns the changed files with a rollback-able transaction.',
         inputSchema: focusRewriteRequestSchema,
         outputSchema: focusPlanOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/gui.js

@@ -72,7 +72,7 @@ export const guiTaskTools = [
     {
         name: 'hoi4.gui_inspect',
         title: 'Inspect scripted GUI',
-        description: 'Inspect GUI sources and scenarios.',
+        description: 'Inspect a scripted GUI window with its linked .gui, .gfx, scripted-GUI, localisation and font sources, and layout diagnostics. Example: {"windowName":"my_window"}. Returns element counts and fidelity inline; the full scene is a linked resource.',
         inputSchema: guiInspectRequestSchema,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
@@ -80,7 +80,7 @@ export const guiTaskTools = [
     {
         name: 'hoi4.gui_render',
         title: 'Render scripted GUI artifacts',
-        description: 'Render GUI states, resolutions, scenarios, hierarchy, comparisons, and diagnostics.',
+        description: 'Render a GUI window under a scenario at several states and resolutions, with click regions, hierarchy and a diagnostics report. Example: {"windowName":"my_window","scenario":{"id":"normal","flags":{"my_flag":true}}}. Returns a gallery of about 25 linked artifacts; undecided visibility stays marked unresolved.',
         inputSchema: guiRenderRequestSchema,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,
@@ -88,7 +88,7 @@ export const guiTaskTools = [
     {
         name: 'hoi4.gui_rewrite',
         title: 'Create or clean up scripted GUI',
-        description: 'Apply one validated source, helper, or exact-patch GUI package. Text dependencies use additionalFiles; binary art stays workspace-referenced.',
+        description: 'Apply one validated GUI change as complete source, structured helpers or exact patches, plus extra text files (additionalFiles); binary art must already be in the mod. Example: {"mode":"helpers","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"helper":{...}}. Writes atomically; returns changed files and a rollback-able transaction.',
         inputSchema: guiRewriteRequestSchema,
         outputSchema: guiPlanOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/job.js

@@ -5,7 +5,7 @@ export const jobControlTools = [
     {
         name: 'hoi4.job_inspect',
         title: 'Inspect persistent job',
-        description: 'Inspect a durable background operation. A completed job returns the original tool result; active and terminal non-result states return bounded status evidence.',
+        description: 'Inspect a background operation by jobId (from a native task id): status while it runs, the original tool result once it completed. Example: {"jobId":"job_<64 hex characters>"}. Returns bounded status evidence.',
         inputSchema: jobReferenceSchema,
         annotations: {
             readOnlyHint: true,
@@ -17,7 +17,7 @@ export const jobControlTools = [
     {
         name: 'hoi4.job_cancel',
         title: 'Cancel persistent job',
-        description: 'Durably request cancellation of an authorized background operation. Completed results remain completed.',
+        description: 'Durably request cancellation of a background operation by jobId. A completed result stays completed. Example: {"jobId":"job_<64 hex characters>"}.',
         inputSchema: jobReferenceSchema,
         outputSchema: jobStatusOutputSchema,
         annotations: {

package/dist/hoi4_agent_tools/mcp/tools/map.js

@@ -1,6 +1,6 @@
 import { registerLegacyTaskTools } from '../server/legacy-task-tools.js';
 import { z } from 'zod/v4';
-import { mapInspectRequestSchema, mapRenderRequestSchema, mapRewriteRequestSchema, } from '../../schemas/map-requests.js';
+import { mapInspectRequestSchema, mapRewriteRequestSchema } from '../../schemas/map-requests.js';
 import { allocationEvidenceSchema, bitmapRenderHashesSchema, nonNegativeIntegerSchema, operationBlockerDataSchema, sha256Schema, } from '../server/output-schemas.js';
 import { strictOperationResultSchema } from '../server/result.js';
 const changedBoundsSchema = z
@@ -55,7 +55,7 @@ const mapSemanticDiffSchema = z
     normalAdjacenciesChanged: z.boolean(),
 })
     .strict();
-const mapWorkspaceInspectOutputSchema = strictOperationResultSchema(z
+const mapWorkspaceInspectDataSchema = z
     .object({
     revision: sha256Schema,
     sharedRevision: sha256Schema,
@@ -78,9 +78,13 @@ const mapWorkspaceInspectOutputSchema = strictOperationResultSchema(z
     lookupOnly: z.boolean().optional(),
     unknownProvinceIds: z.array(nonNegativeIntegerSchema).max(512),
     missingGeometryProvinceIds: z.array(nonNegativeIntegerSchema).max(512),
+    scriptReferences: z
+        .object({ references: nonNegativeIntegerSchema, missing: nonNegativeIntegerSchema })
+        .strict()
+        .optional(),
 })
-    .strict());
-const mapRenderOutputSchema = strictOperationResultSchema(z
+    .strict();
+const mapRenderDataSchema = z
     .object({
     revision: sha256Schema,
     width: nonNegativeIntegerSchema,
@@ -97,7 +101,8 @@ const mapRenderOutputSchema = strictOperationResultSchema(z
         .strict()
         .optional(),
 })
-    .strict());
+    .strict();
+const mapInspectOutputSchema = strictOperationResultSchema(z.union([mapWorkspaceInspectDataSchema, mapRenderDataSchema]));
 const mapPlanOutputSchema = strictOperationResultSchema(z
     .object({
     execution: z.enum(['applied', 'blocked', 'unchanged']),
@@ -123,23 +128,15 @@ export const mapTaskTools = [
     {
         name: 'hoi4.map_inspect',
         title: 'Inspect HOI4 map',
-        description: 'Validate and inspect the complete map, or use lookupOnly for bounded coordinate and entity lookups.',
+        description: 'Validate the map with a searchable navigator, look up provinces, states, regions, names or coordinates (lookupOnly for speed), render a layer, tile or area, or check script references (references:true). Example: {"query":"Brandenburg","lookupOnly":true}. Returns counts and matches inline; PNG, HTML and the catalog are artifacts.',
         inputSchema: mapInspectRequestSchema,
-        outputSchema: mapWorkspaceInspectOutputSchema,
-        annotations: artifactProducing,
-    },
-    {
-        name: 'hoi4.map_render',
-        title: 'Render map inspection artifacts',
-        description: 'Render searchable full-map PNG, JSON, and HTML, or a reusable source-coordinate tile.',
-        inputSchema: mapRenderRequestSchema,
-        outputSchema: mapRenderOutputSchema,
+        outputSchema: mapInspectOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.map_rewrite',
         title: 'Create or clean up map content',
-        description: 'Apply map creation, edits, and ID swaps with visual and semantic evidence.',
+        description: 'Create a world, or create, split, merge, move and renumber states and provinces, regenerate positions and supply, and remap script references. Example: {"operations":[{"id":"s1","kind":"create_state","provinceIds":[120,121],"displayName":"New State"}]}. All or nothing: a failed operation leaves no partial files. Returns changed IDs, semantic diff and a render.',
         inputSchema: mapRewriteRequestSchema,
         outputSchema: mapPlanOutputSchema,
         annotations: {