feat(openapi): include operation description in MCP tool descriptions

.changeset/openapi-mcp-descriptions.md

@@ -0,0 +1,5 @@
+---
+'incur': patch
+---
+
+Included OpenAPI operation descriptions in MCP tool descriptions by concatenating summary and description; CLI help keeps the short summary.

src/Openapi.test.ts

@@ -154,6 +154,19 @@ describe('generateCommands', () => {
     expect(cmd.description).toBe('List users')
   })
 
+  test('command concatenates summary and description for MCP', async () => {
+    const commands = await Openapi.generateCommands(spec, app.fetch)
+    const cmd = commands.get('listUsers')!
+    if ('_group' in cmd) throw new Error('expected listUsers command')
+    expect(cmd.mcp?.description).toBe(
+      'List users\n\nReturns users ordered by creation date. Use `limit` to cap the page size.',
+    )
+    // Summary-only operations get no MCP override.
+    const summaryOnly = commands.get('createUser')!
+    if ('_group' in summaryOnly) throw new Error('expected createUser command')
+    expect(summaryOnly.mcp).toBeUndefined()
+  })
+
   test('coerced number params preserve description', async () => {
     const commands = await Openapi.generateCommands(spec, app.fetch)
     const cmd = commands.get('listUsers')!

src/Openapi.ts

@@ -122,6 +122,7 @@ type FetchHandler = (req: Request) => Response | Promise<Response>
 type GeneratedCommand = {
   args?: z.ZodObject<any> | undefined
   description?: string | undefined
+  mcp?: { description: string } | undefined
   options?: z.ZodObject<any> | undefined
   run: (context: any) => any
 }
@@ -434,6 +435,10 @@ export async function generateCommands(
 
     setCommand(commands, segments, {
       description: op.summary ?? op.description,
+      // Help keeps the short summary; MCP tools surface the full prose.
+      ...(op.summary && op.description && op.summary !== op.description
+        ? { mcp: { description: `${op.summary}\n\n${op.description}` } }
+        : undefined),
       args: argsSchema,
       options: optionsSchema,
       run: createHandler({

test/fixtures/openapi-spec.ts

@@ -7,6 +7,7 @@ export const spec = {
       get: {
         operationId: 'listUsers',
         summary: 'List users',
+        description: 'Returns users ordered by creation date. Use `limit` to cap the page size.',
         parameters: [
           {
             name: 'limit',