@ontrails/mcp 1.0.0-beta.1 → 1.0.0-beta.10

package/src/__tests__/annotations.test.ts

@@ -3,36 +3,39 @@ import { describe, expect, test } from 'bun:test';
 import { deriveAnnotations } from '../annotations.js';
 
 describe('deriveAnnotations', () => {
-  test('readOnly trail produces readOnlyHint', () => {
-    const annotations = deriveAnnotations({ readOnly: true });
+  test('read intent produces readOnlyHint', () => {
+    const annotations = deriveAnnotations({ intent: 'read' });
     expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.destructiveHint).toBeUndefined();
     expect(annotations.idempotentHint).toBeUndefined();
   });
 
-  test('destructive trail produces destructiveHint', () => {
-    const annotations = deriveAnnotations({ destructive: true });
+  test('destroy intent produces destructiveHint', () => {
+    const annotations = deriveAnnotations({ intent: 'destroy' });
     expect(annotations.destructiveHint).toBe(true);
     expect(annotations.readOnlyHint).toBeUndefined();
   });
 
   test('idempotent trail produces idempotentHint', () => {
-    const annotations = deriveAnnotations({ idempotent: true });
+    const annotations = deriveAnnotations({
+      idempotent: true,
+      intent: 'write',
+    });
     expect(annotations.idempotentHint).toBe(true);
   });
 
-  test('multiple markers combine correctly', () => {
+  test('read intent with idempotent combines correctly', () => {
     const annotations = deriveAnnotations({
       idempotent: true,
-      readOnly: true,
+      intent: 'read',
     });
     expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.idempotentHint).toBe(true);
     expect(annotations.destructiveHint).toBeUndefined();
   });
 
-  test('no markers produces empty annotations', () => {
-    const annotations = deriveAnnotations({});
+  test('write intent produces empty annotations', () => {
+    const annotations = deriveAnnotations({ intent: 'write' });
     expect(annotations.readOnlyHint).toBeUndefined();
     expect(annotations.destructiveHint).toBeUndefined();
     expect(annotations.idempotentHint).toBeUndefined();
@@ -42,29 +45,19 @@ describe('deriveAnnotations', () => {
   test('description maps to title', () => {
     const annotations = deriveAnnotations({
       description: 'Show entity details',
+      intent: 'write',
     });
     expect(annotations.title).toBe('Show entity details');
   });
 
-  test('all markers plus description', () => {
+  test('all hints plus description', () => {
     const annotations = deriveAnnotations({
       description: 'A trail',
-      destructive: true,
       idempotent: true,
-      readOnly: true,
+      intent: 'destroy',
     });
-    expect(annotations.readOnlyHint).toBe(true);
     expect(annotations.destructiveHint).toBe(true);
     expect(annotations.idempotentHint).toBe(true);
     expect(annotations.title).toBe('A trail');
   });
-
-  test('false values are not included', () => {
-    const annotations = deriveAnnotations({
-      destructive: false,
-      readOnly: false,
-    });
-    expect(annotations.readOnlyHint).toBeUndefined();
-    expect(annotations.destructiveHint).toBeUndefined();
-  });
 });

package/src/__tests__/blaze.test.ts

@@ -3,14 +3,15 @@ import { describe, expect, test } from 'bun:test';
 import { Result, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { createMcpServer } from '../blaze.js';
+import { blaze, createMcpServer } from '../blaze.js';
 import { buildMcpTools } from '../build.js';
+import type { McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
 
-const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
+const requireTool = (tools: McpToolDefinition[], name: string) => {
   const tool = tools.find((entry) => entry.name === name);
   expect(tool).toBeDefined();
   if (!tool) {
@@ -19,35 +20,79 @@ const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
   return tool;
 };
 
+/**
+ * Unwrap buildMcpTools result, throwing on error so test failures surface clearly.
+ */
+const buildTools = (
+  ...args: Parameters<typeof buildMcpTools>
+): McpToolDefinition[] => {
+  const result = buildMcpTools(...args);
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
 const createIntegrationTools = () => {
   const greetTrail = trail('greet', {
     description: 'Greet someone',
-    implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
     input: z.object({ name: z.string() }),
-    readOnly: true,
+    intent: 'read',
+    run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
   });
 
   const deleteTrail = trail('item.delete', {
     description: 'Delete an item',
-    destructive: true,
-    implementation: (_input) => Result.ok({ deleted: true }),
     input: z.object({ id: z.string() }),
+    intent: 'destroy',
+    run: (_input) => Result.ok({ deleted: true }),
   });
 
-  return buildMcpTools(topo('myapp', { deleteTrail, greetTrail }));
+  return buildTools(topo('myapp', { deleteTrail, greetTrail }));
 };
 
 describe('blaze', () => {
+  test('blaze throws on invalid topo', async () => {
+    const t = trail('broken', {
+      follow: ['nonexistent.trail'],
+      input: z.object({}),
+      output: z.object({}),
+      run: () => Result.ok({}),
+    });
+    const app = topo('test', { t });
+    await expect(blaze(app)).rejects.toThrow(/validation/i);
+  });
+
+  test('blaze skips validation when validate: false', async () => {
+    const t = trail('broken', {
+      follow: ['nonexistent.trail'],
+      input: z.object({}),
+      output: z.object({}),
+      run: () => Result.ok({}),
+    });
+    const app = topo('test', { t });
+    const result = await Promise.race([
+      blaze(app, { validate: false }).then(() => 'resolved' as const),
+      // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based timeout
+      new Promise<'timeout'>((resolve) => {
+        setTimeout(() => {
+          resolve('timeout');
+        }, 50);
+      }),
+    ]);
+    expect(['resolved', 'timeout']).toContain(result);
+  });
+
   test('createMcpServer registers tools that can be listed', () => {
     const echoTrail = trail('echo', {
       description: 'Echo',
-      implementation: (input) => Result.ok({ reply: input.message }),
       input: z.object({ message: z.string() }),
-      readOnly: true,
+      intent: 'read',
+      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const app = topo('testapp', { echoTrail });
-    const tools = buildMcpTools(app);
+    const tools = buildTools(app);
     const server = createMcpServer(tools, {
       name: 'testapp',
       version: '0.1.0',
@@ -60,19 +105,19 @@ describe('blaze', () => {
   test('createMcpServer handles multiple tools', () => {
     const echoTrail = trail('echo', {
       description: 'Echo',
-      implementation: (input) => Result.ok({ reply: input.message }),
       input: z.object({ message: z.string() }),
+      run: (input) => Result.ok({ reply: input.message }),
     });
 
     const searchTrail = trail('search', {
       description: 'Search',
-      implementation: (input) => Result.ok({ results: [input.query] }),
       input: z.object({ query: z.string() }),
-      readOnly: true,
+      intent: 'read',
+      run: (input) => Result.ok({ results: [input.query] }),
     });
 
     const app = topo('testapp', { echoTrail, searchTrail });
-    const tools = buildMcpTools(app);
+    const tools = buildTools(app);
 
     expect(tools).toHaveLength(2);
 

package/src/__tests__/build.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, test } from 'bun:test';
 
-import { Result, trail, topo } from '@ontrails/core';
+import { Result, createBlobRef, trail, topo } from '@ontrails/core';
 import type { Layer } from '@ontrails/core';
 import { z } from 'zod';
 
 import { buildMcpTools } from '../build.js';
-import type { McpExtra } from '../build.js';
+import type { McpExtra, McpToolDefinition } from '../build.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -13,23 +13,23 @@ import type { McpExtra } from '../build.js';
 
 const echoTrail = trail('echo', {
   description: 'Echo a message back',
-  implementation: (input) => Result.ok({ reply: input.message }),
   input: z.object({ message: z.string() }),
+  intent: 'read',
   output: z.object({ reply: z.string() }),
-  readOnly: true,
+  run: (input) => Result.ok({ reply: input.message }),
 });
 
 const deleteTrail = trail('item.delete', {
   description: 'Delete an item',
-  destructive: true,
-  implementation: (_input) => Result.ok({ deleted: true }),
   input: z.object({ id: z.string() }),
+  intent: 'destroy',
+  run: (_input) => Result.ok({ deleted: true }),
 });
 
 const failTrail = trail('fail', {
   description: 'Always fails',
-  implementation: (input) => Result.err(new Error(input.reason)),
   input: z.object({ reason: z.string() }),
+  run: (input) => Result.err(new Error(input.reason)),
 });
 
 const exampleTrail = trail('with.examples', {
@@ -41,13 +41,13 @@ const exampleTrail = trail('with.examples', {
       name: 'basic',
     },
   ],
-  implementation: (input) => Result.ok({ greeting: `hello ${input.name}` }),
   input: z.object({ name: z.string() }),
+  run: (input) => Result.ok({ greeting: `hello ${input.name}` }),
 });
 
 const noExtra: McpExtra = {};
 
-const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
+const requireTool = (tools: McpToolDefinition[], name: string) => {
   const tool = tools.find((entry) => entry.name === name);
   expect(tool).toBeDefined();
   if (!tool) {
@@ -56,7 +56,7 @@ const requireTool = (tools: ReturnType<typeof buildMcpTools>, name: string) => {
   return tool;
 };
 
-const requireOnlyTool = (tools: ReturnType<typeof buildMcpTools>) => {
+const requireOnlyTool = (tools: McpToolDefinition[]) => {
   expect(tools).toHaveLength(1);
   const [tool] = tools;
   expect(tool).toBeDefined();
@@ -66,6 +66,20 @@ const requireOnlyTool = (tools: ReturnType<typeof buildMcpTools>) => {
   return tool;
 };
 
+/**
+ * Unwrap buildMcpTools result for success-path tests.
+ * Throws if the result is an error so test failures surface clearly.
+ */
+const buildTools = (
+  ...args: Parameters<typeof buildMcpTools>
+): McpToolDefinition[] => {
+  const result = buildMcpTools(...args);
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
 const parseJsonContent = (
   content: { readonly text?: string | undefined } | undefined
 ): unknown => {
@@ -81,7 +95,7 @@ describe('buildMcpTools', () => {
   describe('discovery', () => {
     test('builds tools from a single-trail app', () => {
       const app = topo('myapp', { echoTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(tools).toHaveLength(1);
       expect(requireOnlyTool(tools).name).toBe('myapp_echo');
@@ -89,7 +103,7 @@ describe('buildMcpTools', () => {
 
     test('builds tools from a multi-trail app', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(tools).toHaveLength(3);
       const names = tools.map((t) => t.name);
@@ -100,14 +114,14 @@ describe('buildMcpTools', () => {
 
     test('tool names follow derivation rules', () => {
       const app = topo('myapp', { deleteTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(requireOnlyTool(tools).name).toBe('myapp_item_delete');
     });
 
     test('input schema is valid JSON Schema', () => {
       const app = topo('myapp', { echoTrail });
-      const schema = requireOnlyTool(buildMcpTools(app)).inputSchema;
+      const schema = requireOnlyTool(buildTools(app)).inputSchema;
 
       expect(schema['type']).toBe('object');
       expect(schema['properties']).toBeDefined();
@@ -117,7 +131,7 @@ describe('buildMcpTools', () => {
 
     test('annotations are correctly derived', () => {
       const app = topo('myapp', { deleteTrail, echoTrail });
-      const tools = buildMcpTools(app);
+      const tools = buildTools(app);
 
       expect(requireTool(tools, 'myapp_echo').annotations?.readOnlyHint).toBe(
         true
@@ -129,12 +143,22 @@ describe('buildMcpTools', () => {
         requireTool(tools, 'myapp_item_delete').annotations?.destructiveHint
       ).toBe(true);
     });
+
+    test('trailId identifies the source trail', () => {
+      const app = topo('myapp', { deleteTrail, echoTrail });
+      const tools = buildTools(app);
+
+      expect(requireTool(tools, 'myapp_echo').trailId).toBe('echo');
+      expect(requireTool(tools, 'myapp_item_delete').trailId).toBe(
+        'item.delete'
+      );
+    });
   });
 
   describe('handler execution', () => {
     test('handler validates input and returns isError on invalid', async () => {
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ notMessage: 123 }, noExtra);
       expect(result?.isError).toBe(true);
@@ -144,7 +168,7 @@ describe('buildMcpTools', () => {
 
     test('handler calls implementation and returns result as text content', async () => {
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ message: 'hello' }, noExtra);
       expect(result?.isError).toBeUndefined();
@@ -156,7 +180,7 @@ describe('buildMcpTools', () => {
 
     test('handler maps errors to isError content', async () => {
       const app = topo('myapp', { failTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       const result = await tool.handler({ reason: 'broken' }, noExtra);
       expect(result?.isError).toBe(true);
@@ -165,15 +189,13 @@ describe('buildMcpTools', () => {
 
     test('handler catches thrown exceptions', async () => {
       const throwTrail = trail('throw', {
-        implementation: () => {
+        input: z.object({}),
+        run: () => {
           throw new Error('unexpected crash');
         },
-        input: z.object({}),
       });
 
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('myapp', { throwTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('myapp', { throwTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.isError).toBe(true);
@@ -184,7 +206,7 @@ describe('buildMcpTools', () => {
   describe('filters', () => {
     test('include filter limits which trails become tools', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         includeTrails: ['echo'],
       });
 
@@ -194,7 +216,7 @@ describe('buildMcpTools', () => {
 
     test('exclude filter removes specific trails', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         excludeTrails: ['fail'],
       });
 
@@ -205,7 +227,7 @@ describe('buildMcpTools', () => {
 
     test('include takes precedence over exclude', () => {
       const app = topo('myapp', { deleteTrail, echoTrail, failTrail });
-      const tools = buildMcpTools(app, {
+      const tools = buildTools(app, {
         excludeTrails: ['fail'],
         includeTrails: ['echo', 'fail'],
       });
@@ -234,7 +256,7 @@ describe('buildMcpTools', () => {
       };
 
       const app = topo('myapp', { echoTrail });
-      const tool = requireOnlyTool(buildMcpTools(app, { layers: [testLayer] }));
+      const tool = requireOnlyTool(buildTools(app, { layers: [testLayer] }));
 
       await tool.handler({ message: 'hi' }, noExtra);
       expect(calls).toEqual(['before', 'after']);
@@ -244,17 +266,15 @@ describe('buildMcpTools', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.check', {
-        implementation: (_input, ctx) => {
+        input: z.object({}),
+        run: (_input, ctx) => {
           capturedSignal = ctx.signal;
           return Result.ok({ ok: true });
         },
-        input: z.object({}),
       });
 
       const controller = new AbortController();
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('myapp', { signalTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('myapp', { signalTrail })));
 
       await tool.handler({}, { signal: controller.signal });
       expect(capturedSignal).toBe(controller.signal);
@@ -262,7 +282,7 @@ describe('buildMcpTools', () => {
 
     test('description includes first example input when present', () => {
       const app = topo('myapp', { exampleTrail });
-      const tool = requireOnlyTool(buildMcpTools(app));
+      const tool = requireOnlyTool(buildTools(app));
 
       expect(tool.description).toContain('A trail with examples');
       expect(tool.description).toContain('"name":"world"');
@@ -272,19 +292,18 @@ describe('buildMcpTools', () => {
       let contextUsed = false;
 
       const ctxTrail = trail('ctx.check', {
-        implementation: (_input, ctx) => {
-          const ctxRecord = ctx as Record<string, unknown>;
-          contextUsed = ctxRecord['custom'] === true;
+        input: z.object({}),
+        run: (_input, ctx) => {
+          contextUsed = ctx.extensions?.['custom'] === true;
           return Result.ok({ ok: true });
         },
-        input: z.object({}),
       });
 
       const app = topo('myapp', { ctxTrail });
       const tool = requireOnlyTool(
-        buildMcpTools(app, {
+        buildTools(app, {
           createContext: () => ({
-            custom: true,
+            extensions: { custom: true },
             requestId: 'test-id',
             signal: new AbortController().signal,
           }),
@@ -299,17 +318,19 @@ describe('buildMcpTools', () => {
   describe('blob outputs', () => {
     test('BlobRef output converts to image content', async () => {
       const blobTrail = trail('blob.image', {
-        implementation: () =>
-          Result.ok({
-            data: new Uint8Array([1, 2, 3]),
-            kind: 'blob' as const,
-            mimeType: 'image/png',
-            name: 'test.png',
-          }),
         input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: new Uint8Array([1, 2, 3]),
+              mimeType: 'image/png',
+              name: 'test.png',
+              size: 3,
+            })
+          ),
       });
 
-      const tool = requireOnlyTool(buildMcpTools(topo('myapp', { blobTrail })));
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.content[0]?.type).toBe('image');
@@ -319,23 +340,103 @@ describe('buildMcpTools', () => {
 
     test('BlobRef output converts to resource content for non-images', async () => {
       const blobTrail = trail('blob.file', {
-        implementation: () =>
-          Result.ok({
-            data: new Uint8Array([1, 2, 3]),
-            kind: 'blob' as const,
-            mimeType: 'application/pdf',
-            name: 'doc.pdf',
-          }),
         input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: new Uint8Array([1, 2, 3]),
+              mimeType: 'application/pdf',
+              name: 'doc.pdf',
+              size: 3,
+            })
+          ),
       });
 
-      const tool = requireOnlyTool(buildMcpTools(topo('myapp', { blobTrail })));
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
       const result = await tool.handler({}, noExtra);
 
       expect(result?.content[0]?.type).toBe('resource');
       expect(result?.content[0]?.uri).toBe('blob://doc.pdf');
       expect(result?.content[0]?.mimeType).toBe('application/pdf');
     });
+
+    test('BlobRef with ReadableStream data is collected and serialized', async () => {
+      const bytes = new Uint8Array([10, 20, 30]);
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(bytes);
+          controller.close();
+        },
+      });
+      const blobTrail = trail('blob.stream', {
+        input: z.object({}),
+        run: () =>
+          Result.ok(
+            createBlobRef({
+              data: stream,
+              mimeType: 'image/gif',
+              name: 'anim.gif',
+              size: 3,
+            })
+          ),
+      });
+
+      const tool = requireOnlyTool(buildTools(topo('myapp', { blobTrail })));
+      const result = await tool.handler({}, noExtra);
+
+      expect(result?.content[0]?.type).toBe('image');
+      expect(result?.content[0]?.mimeType).toBe('image/gif');
+      expect(result?.content[0]?.data).toBeDefined();
+    });
+  });
+
+  describe('tool-name collision detection', () => {
+    test('returns Err on trails that produce the same derived tool name', () => {
+      const dotTrail = trail('foo.bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const underscoreTrail = trail('foo_bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { dotTrail, underscoreTrail });
+      const result = buildMcpTools(app);
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/tool-name collision/i);
+    });
+
+    test('returns Err on trails where hyphen and underscore collide', () => {
+      const hyphenTrail = trail('foo-bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const underscoreTrail = trail('foo_bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { hyphenTrail, underscoreTrail });
+      const result = buildMcpTools(app);
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toMatch(/tool-name collision/i);
+    });
+
+    test('returns Ok when trail names are distinct after normalization', () => {
+      const fooTrail = trail('foo', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+      const barTrail = trail('bar', {
+        input: z.object({}),
+        run: () => Result.ok({ ok: true }),
+      });
+
+      const app = topo('myapp', { barTrail, fooTrail });
+      const result = buildMcpTools(app);
+      expect(result.isOk()).toBe(true);
+    });
   });
 
   describe('end-to-end', () => {
@@ -343,16 +444,13 @@ describe('buildMcpTools', () => {
       const greetTrail = trail('greet', {
         description: 'Greet someone',
         idempotent: true,
-        implementation: (input) =>
-          Result.ok({ greeting: `Hello, ${input.name}!` }),
         input: z.object({ name: z.string() }),
+        intent: 'read',
         output: z.object({ greeting: z.string() }),
-        readOnly: true,
+        run: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
       });
 
-      const tool = requireOnlyTool(
-        buildMcpTools(topo('testapp', { greetTrail }))
-      );
+      const tool = requireOnlyTool(buildTools(topo('testapp', { greetTrail })));
 
       expect(tool).toMatchObject({
         annotations: {

package/src/annotations.ts

@@ -1,8 +1,8 @@
 /**
- * Derive MCP tool annotations from trail spec markers.
+ * Derive MCP tool annotations from trail spec fields.
  */
 
-import type { Trail } from '@ontrails/core';
+import type { Intent, Trail } from '@ontrails/core';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -27,18 +27,18 @@ export interface McpAnnotations {
  * Omitted hints let the MCP SDK use its defaults.
  */
 export const deriveAnnotations = (
-  trail: Pick<
-    Trail<unknown, unknown>,
-    'readOnly' | 'destructive' | 'idempotent' | 'description'
-  >
+  trail: Pick<Trail<unknown, unknown>, 'intent' | 'idempotent' | 'description'>
 ): McpAnnotations => {
   const annotations: Record<string, unknown> = {};
 
-  if (trail.readOnly === true) {
-    annotations['readOnlyHint'] = true;
-  }
-  if (trail.destructive === true) {
-    annotations['destructiveHint'] = true;
+  const intentToHint: Partial<Record<Intent, string>> = {
+    destroy: 'destructiveHint',
+    read: 'readOnlyHint',
+  };
+
+  const hint = intentToHint[trail.intent];
+  if (hint) {
+    annotations[hint] = true;
   }
   if (trail.idempotent === true) {
     annotations['idempotentHint'] = true;