hoi4-agent-tools 3.10.0 → 4.0.1

package/dist/hoi4_agent_tools/mcp/prompts/probability.js

@@ -5,8 +5,8 @@ export const probabilityPromptArguments = z.object({
 });
 export const probabilityPromptDefinition = {
     name: 'hoi4.probability_analysis',
-    title: 'Analyze HOI4 weighted logic',
-    description: 'Plan one source-linked AI, MTTH, random, or declared-pool analysis and return to the owning modding workflow.',
+    title: 'Analyze AI choices and event timing',
+    description: 'Outline an analysis of AI choices, event timing, random chances or a custom weighted pool.',
 };
 /** One prompt body for both protocol generations; it does not run an analysis. */
 export function probabilityPrompt(input) {

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/instructions.js

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-export const SERVER_INSTRUCTIONS = 'Start with the matching inspect tool; use hoi4.probability_inspect for weights and timing. Find local documentation with hoi4.reference_context, hoi4.reference_search and hoi4.reference_read, and source definitions with hoi4.source_lookup. Inspection and rendering are read-only; rewrite tools edit mod source. Results describe offline source and scenario models, not observed game behavior. Unresolved states are not confirmed coverage. Read linked artifacts when summaries omit detail. Long operations support negotiated MCP tasks and hoi4.job_inspect/hoi4.job_cancel; background rewrites need a stable requestKey.';
+export const SERVER_INSTRUCTIONS = 'Start with the matching inspect tool; use hoi4.probability_inspect for weights and timing. Find local documentation with hoi4.reference_context, hoi4.reference_search and hoi4.reference_read, and source definitions with hoi4.source_lookup. Rewrite tools edit mod source. Results describe offline source and scenario models, not observed game behavior. Unresolved states are not confirmed coverage. Read linked artifacts when summaries omit detail. Long operations support negotiated MCP tasks and hoi4.job_inspect/hoi4.job_cancel; background rewrites need a stable requestKey.';

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
@@ -92,7 +112,7 @@ const packageInputSchema = z
 const scenarioInputSchema = z
     .object({
     ...scenarioTestRequestSchema.shape,
-    suite: compactValidatedInputSchema(scenarioSuiteSchema, 'Named mechanic, package, or fixed read-only tool cases. See docs/mechanics.md.').optional(),
+    suite: compactValidatedInputSchema(scenarioSuiteSchema, 'Named mechanic, package or inspection cases. See docs/mechanics.md.').optional(),
 })
     .strict()
     .superRefine((input, context) => {
@@ -111,8 +131,8 @@ const readOnlyAnalysisTool = {
 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.',
+        title: 'Find what a script change affects',
+        description: 'Find what a script change affects across focuses, events, decisions, ideas, windows and helpers. Trace definitions and their uses, including proposed source. 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,15 +140,15 @@ 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: 'Explain why a decision or mission is hidden, unavailable or unaffordable. Inspect conditions, costs and lifecycle for declared actors and targets, or compare proposed source. 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,
     },
     {
         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.',
+        title: 'Test scripted effects',
+        description: 'Test what an effect, event option, decision or focus reward does to a declared state. Run steps and check assertions; unsupported effects stay unresolved. See docs/mechanics.md. Example: {"test":{"id":"t","scenario":{"schemaVersion":"1.0","id":"t","state":{"treasury":10}},"steps":[...],"assertions":[...]}}.',
         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: 'Find missing pieces of a feature by checking its package manifest against definitions, calls, registrations, localisation, assets and required test 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 named mechanic, package or inspection cases from a suite or workspace file. Continue unfinished batches and report failures and unresolved cases. 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,27 +169,19 @@ 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: 'Follow event chains and explain their options, conditions, timing and state changes. Find broken calls, inspect affected events or compare revisions with mode compare. 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,
     },
     {
         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.',
+        title: 'Preview event chains',
+        description: 'Preview event routes, options, timing, state and scope 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,31 +135,23 @@ 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: 'Find focus branches, prerequisites, layout problems and missing references in national trees and continuous-focus palettes. 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: 'Preview a focus tree or continuous palette',
+        description: 'Preview a focus tree or palette with its icons. Export PNG, HTML, SVG and JSON source maps; png:false skips the PNG and 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,
     },
     {
         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.',
+        title: 'Build or arrange a focus tree',
+        description: 'Create focus trees and continuous-focus palettes, or rearrange existing branches. Use createIfMissing with a complete plan to create content, or layoutMode to arrange an existing tree. Example: {"relativePath":"common/national_focus/my_tree.txt","treeId":"my_focus_tree","layoutMode":"compact"}. Returns the changed files.',
         inputSchema: focusRewriteRequestSchema,
         outputSchema: focusPlanOutputSchema,
         annotations: {

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

@@ -71,24 +71,24 @@ const artifactProducing = {
 export const guiTaskTools = [
     {
         name: 'hoi4.gui_inspect',
-        title: 'Inspect scripted GUI',
-        description: 'Inspect GUI sources and scenarios.',
+        title: 'Inspect a window',
+        description: 'Find the elements, assets and script behind a window, including layout problems, localisation and fonts. Example: {"windowName":"my_window"}. Returns element counts and fidelity inline; the full scene is a linked resource.',
         inputSchema: guiInspectRequestSchema,
         outputSchema: guiScanOutputSchema,
         annotations: artifactProducing,
     },
     {
         name: 'hoi4.gui_render',
-        title: 'Render scripted GUI artifacts',
-        description: 'Render GUI states, resolutions, scenarios, hierarchy, comparisons, and diagnostics.',
+        title: 'Preview a window',
+        description: 'Preview a window at different resolutions and states. Shows control regions, element hierarchy and layout problems; unknown visibility stays unresolved. Example: {"windowName":"my_window","scenario":{"id":"normal","flags":{"my_flag":true}}}. Images and reports are linked resources.',
         inputSchema: guiRenderRequestSchema,
         outputSchema: guiRenderOutputSchema,
         annotations: artifactProducing,
     },
     {
         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.',
+        title: 'Create or edit a window',
+        description: 'Create or edit a window using complete source, structured helpers or exact patches. Include related text files with additionalFiles; binary art must already be in the mod. Example: {"mode":"helpers","relativePath":"interface/my_window.gui","windowName":"my_window","scenario":{"id":"normal"},"helper":{...}}. Returns the changed files.',
         inputSchema: guiRewriteRequestSchema,
         outputSchema: guiPlanOutputSchema,
         annotations: {

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

@@ -4,8 +4,8 @@ import { errorResult } from '../../core/operation-result.js';
 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.',
+        title: 'Check a background task',
+        description: 'Check progress on a background task or retrieve its completed result. Pass jobId from the task handle. Example: {"jobId":"job_<64 hex characters>"}. Returns task status or the completed result.',
         inputSchema: jobReferenceSchema,
         annotations: {
             readOnlyHint: true,
@@ -16,8 +16,8 @@ export const jobControlTools = [
     },
     {
         name: 'hoi4.job_cancel',
-        title: 'Cancel persistent job',
-        description: 'Durably request cancellation of an authorized background operation. Completed results remain completed.',
+        title: 'Stop a background task',
+        description: 'Stop a background task by jobId. A result that has already completed stays available. Example: {"jobId":"job_<64 hex characters>"}.',
         inputSchema: jobReferenceSchema,
         outputSchema: jobStatusOutputSchema,
         annotations: {