@opencapstack/mcp-server 0.1.3 → 0.1.4

package/dist/tools/valuations.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt, coerceFloat } from '../schema.js';
 export const valuationTools = [
     {
         name: 'get_latest_valuation',
@@ -7,7 +8,9 @@ export const valuationTools = [
             companyId: z.string().describe('Company ID'),
         }),
         handler: async (input, client) => {
-            const { data } = await client.get(`/api/v1/valuations/latest`, { params: { companyId: input.companyId } });
+            const { data } = await client.get('/api/v1/valuations/latest', {
+                params: { companyId: input.companyId },
+            });
             return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
         },
     },
@@ -16,7 +19,7 @@ export const valuationTools = [
         description: 'Get the historical valuation timeline for the company.',
         inputSchema: z.object({
             companyId: z.string().describe('Company ID'),
-            limit: z.number().optional().default(20).describe('Max results to return'),
+            limit: coerceInt('Max results to return').optional().default(20),
         }),
         handler: async (input, client) => {
             const { data } = await client.get('/api/v1/valuations', { params: input });
@@ -35,15 +38,8 @@ export const valuationTools = [
                 .enum(['409A', 'board_approved', 'preferred_round', 'other'])
                 .describe('Type of valuation'),
             valuationDate: z.string().describe('Effective date in ISO 8601 format (YYYY-MM-DD)'),
-            commonStockFMV: z
-                .union([z.number(), z.string()])
-                .transform((v) => parseFloat(String(v)))
-                .describe('Fair market value per common share in USD'),
-            postMoneyValuation: z
-                .union([z.number(), z.string()])
-                .transform((v) => parseFloat(String(v)))
-                .optional()
-                .describe('Total post-money company valuation in USD'),
+            commonStockFMV: coerceFloat('Fair market value per common share in USD'),
+            postMoneyValuation: coerceFloat('Total post-money company valuation in USD').optional(),
             provider: z
                 .string()
                 .optional()
@@ -55,12 +51,29 @@ export const valuationTools = [
                 .describe('URL to the valuation report document'),
         }),
         handler: async (input, client) => {
-            const { data } = await client.post('/api/v1/valuations', input);
-            return {
-                content: [
-                    { type: 'text', text: `Valuation recorded: ${JSON.stringify(data, null, 2)}` },
-                ],
-            };
+            const { data: created } = await client.post('/api/v1/valuations', input);
+            const id = created.row_id ?? created._id;
+            try {
+                const { data: confirmed } = await client.get(`/api/v1/valuations/${id}`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Valuation recorded:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+                        },
+                    ],
+                };
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Valuation recorded (could not confirm persisted state — verify with get_valuation_history):\n${JSON.stringify(created, null, 2)}`,
+                        },
+                    ],
+                };
+            }
         },
     },
 ];

package/dist/tools/valuations.js.map

@@ -1 +1 @@
-{"version":3,"file":"valuations.js","sourceRoot":"","sources":["../../src/tools/valuations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"valuations.js","sourceRoot":"","sources":["../../src/tools/valuations.ts"],"names":[],"mappings":"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"}

package/dist/tools/waterfall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"waterfall.d.ts","sourceRoot":"","sources":["../../src/tools/waterfall.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,cAAc,EA4C1C,CAAC"}
+{"version":3,"file":"waterfall.d.ts","sourceRoot":"","sources":["../../src/tools/waterfall.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,cAAc,EAwC1C,CAAC"}

package/dist/tools/waterfall.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceFloat, coerceBool } from '../schema.js';
 export const waterfallTools = [
     {
         name: 'run_waterfall_analysis',
@@ -7,29 +8,19 @@ export const waterfallTools = [
             'Returns proceeds per stakeholder and per share class at the given exit amount.',
         inputSchema: z.object({
             companyId: z.string().describe('Company ID'),
-            exitAmount: z
-                .number()
-                .positive()
-                .describe('Total exit/acquisition proceeds in USD'),
+            exitAmount: coerceFloat('Total exit/acquisition proceeds in USD'),
             exitType: z
                 .enum(['acquisition', 'ipo', 'dissolution'])
                 .optional()
                 .default('acquisition')
                 .describe('Type of exit event'),
-            deductTransactionCosts: z
-                .boolean()
+            deductTransactionCosts: coerceBool('Whether to deduct estimated transaction costs before distribution')
                 .optional()
-                .default(false)
-                .describe('Whether to deduct estimated transaction costs before distribution'),
-            transactionCostsAmount: z
-                .number()
+                .default(false),
+            transactionCostsAmount: coerceFloat('Transaction costs amount in USD (used if deductTransactionCosts is true)').optional(),
+            includeOptionPoolSweep: coerceBool('Whether to include pre-exit option pool sweep')
                 .optional()
-                .describe('Transaction costs amount in USD (used if deductTransactionCosts is true)'),
-            includeOptionPoolSweep: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe('Whether to include pre-exit option pool sweep'),
+                .default(false),
             asOfDate: z
                 .string()
                 .optional()

package/dist/tools/waterfall.js.map

@@ -1 +1 @@
-{"version":3,"file":"waterfall.js","sourceRoot":"","sources":["../../src/tools/waterfall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C;QACE,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,iFAAiF;YACjF,yFAAyF;YACzF,gFAAgF;QAClF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC5C,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,wCAAwC,CAAC;YACrD,QAAQ,EAAE,CAAC;iBACR,IAAI,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;iBAC3C,QAAQ,EAAE;iBACV,OAAO,CAAC,aAAa,CAAC;iBACtB,QAAQ,CAAC,oBAAoB,CAAC;YACjC,sBAAsB,EAAE,CAAC;iBACtB,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CAAC,mEAAmE,CAAC;YAChF,sBAAsB,EAAE,CAAC;iBACtB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,0EAA0E,CAAC;YACvF,sBAAsB,EAAE,CAAC;iBACtB,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CAAC,+CAA+C,CAAC;YAC5D,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,8EAA8E,CAAC;SAC5F,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YAC/B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;YACvE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aACjE,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}
+{"version":3,"file":"waterfall.js","sourceRoot":"","sources":["../../src/tools/waterfall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGvD,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C;QACE,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,iFAAiF;YACjF,yFAAyF;YACzF,gFAAgF;QAClF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC5C,UAAU,EAAE,WAAW,CAAC,wCAAwC,CAAC;YACjE,QAAQ,EAAE,CAAC;iBACR,IAAI,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;iBAC3C,QAAQ,EAAE;iBACV,OAAO,CAAC,aAAa,CAAC;iBACtB,QAAQ,CAAC,oBAAoB,CAAC;YACjC,sBAAsB,EAAE,UAAU,CAChC,mEAAmE,CACpE;iBACE,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;YACjB,sBAAsB,EAAE,WAAW,CACjC,0EAA0E,CAC3E,CAAC,QAAQ,EAAE;YACZ,sBAAsB,EAAE,UAAU,CAChC,+CAA+C,CAChD;iBACE,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;YACjB,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,8EAA8E,CAAC;SAC5F,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YAC/B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;YACvE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aACjE,CAAC;QACJ,CAAC;KACF;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencapstack/mcp-server",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MCP server for OpenCap Stack — manage your cap table via Claude, Cursor, and any MCP-compatible client",
   "type": "module",
   "bin": {

package/src/auth.ts

@@ -15,5 +15,11 @@ export function getApiKey(): string {
 }
 
 export function getBaseUrl(): string {
-  return process.env.OPENCAP_BASE_URL ?? 'https://api.opencapstack.com';
+  const url = process.env.OPENCAP_BASE_URL ?? 'https://api.opencapstack.com';
+  if (url.includes('/api/v1')) {
+    process.stderr.write(
+      `Warning: OPENCAP_BASE_URL should not include /api/v1 — tools already prefix this path. Current value: ${url}\n`
+    );
+  }
+  return url;
 }

package/src/client.ts

@@ -20,25 +20,42 @@ export function createClient(apiKey: string): AxiosInstance {
     (response) => response,
     (error) => {
       const status = error.response?.status;
+      const message =
+        error.response?.data?.message ??
+        error.response?.data?.error ??
+        error.message ??
+        'Unknown error';
+      const path = error.config?.url ?? '';
 
       if (status === 401) {
         throw new McpError(
           ErrorCode.InvalidRequest,
-          'API key rejected or expired — regenerate at https://app.opencapstack.com/settings'
+          'API key rejected or expired. Regenerate at https://app.opencapstack.com/settings, or run the whoami tool to test your current key.'
         );
       }
 
       if (status === 403) {
         throw new McpError(
           ErrorCode.InvalidRequest,
-          'Access denied — check your account permissions'
+          'Access denied. Check that your token companyId matches the companyId in your request.'
         );
       }
 
-      // Re-throw other errors with the server message when available
-      const message =
-        error.response?.data?.message ?? error.message ?? 'Unknown API error';
-      throw new McpError(ErrorCode.InternalError, `OpenCap API error: ${message}`);
+      if (status === 404) {
+        const idHint = path.match(/\/([^/]+)$/)
+          ? ' Make sure you are using the domain ID field (e.g. safeId, row_id) from a list_* call, not the _id field.'
+          : '';
+        throw new McpError(ErrorCode.InvalidRequest, `Record not found.${idHint}`);
+      }
+
+      if (status === 500) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Server error saving record: ${message}. Check that all referenced IDs exist (e.g. equityPlanId, employeeId, companyId) and try again.`
+        );
+      }
+
+      throw new McpError(ErrorCode.InternalError, `OpenCap API error (${status}): ${message}`);
     }
   );
 

package/src/schema.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared Zod coercion helpers for MCP tool input schemas.
+ *
+ * MCP clients (including Claude Code) send all arguments as strings. These
+ * helpers accept both the native type and a string representation and coerce
+ * to the appropriate JavaScript primitive so tools work correctly regardless
+ * of how the client serialises values.
+ */
+
+import { z } from 'zod';
+
+export const coerceInt = (description: string) =>
+  z
+    .union([z.number(), z.string()])
+    .transform((v) => parseInt(String(v), 10))
+    .describe(description);
+
+export const coerceFloat = (description: string) =>
+  z
+    .union([z.number(), z.string()])
+    .transform((v) => parseFloat(String(v)))
+    .describe(description);
+
+export const coerceBool = (description: string) =>
+  z
+    .union([z.boolean(), z.string()])
+    .transform((v) => v === true || v === 'true')
+    .describe(description);

package/src/server.ts

@@ -22,12 +22,16 @@ import { valuationTools } from './tools/valuations.js';
 import { dilutionTools } from './tools/dilution.js';
 import { waterfallTools } from './tools/waterfall.js';
 import { financialReportTools } from './tools/financialReports.js';
+import { equityGrantTools } from './tools/equityGrants.js';
+import { metaTools } from './tools/meta.js';
 import { type ToolDefinition } from './types.js';
 
 const ALL_TOOLS: ToolDefinition[] = [
+  ...metaTools,
   ...stakeholderTools,
   ...shareClassTools,
   ...equityPlanTools,
+  ...equityGrantTools,
   ...safeTools,
   ...documentTools,
   ...valuationTools,
@@ -40,7 +44,7 @@ export function createServer(client: AxiosInstance): Server {
   const server = new Server(
     {
       name: 'opencap-mcp',
-      version: '0.1.0',
+      version: '0.1.4',
     },
     {
       capabilities: {

package/src/tools/dilution.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt, coerceBool } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const dilutionTools: ToolDefinition[] = [
@@ -9,21 +10,19 @@ export const dilutionTools: ToolDefinition[] = [
       'Returns pre- and post-dilution ownership percentages for each stakeholder.',
     inputSchema: z.object({
       companyId: z.string().describe('Company ID'),
-      newSharesIssued: z
-        .number()
-        .int()
-        .positive()
-        .describe('Number of new shares to be issued in the scenario'),
-      includeOptionPool: z
-        .boolean()
+      newSharesIssued: coerceInt(
+        'Number of new shares to be issued in the scenario'
+      ),
+      includeOptionPool: coerceBool(
+        'Whether to include unissued option pool shares in the denominator'
+      )
         .optional()
-        .default(false)
-        .describe('Whether to include unissued option pool shares in the denominator'),
-      includeSafes: z
-        .boolean()
+        .default(false),
+      includeSafes: coerceBool(
+        'Whether to include SAFEs in conversion when calculating dilution'
+      )
         .optional()
-        .default(true)
-        .describe('Whether to include SAFEs in conversion when calculating dilution'),
+        .default(true),
     }),
     handler: async (input, client) => {
       const { data } = await client.post('/api/v1/dilution/calculate', input);

package/src/tools/documents.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const documentTools: ToolDefinition[] = [
@@ -23,7 +24,7 @@ export const documentTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe('Filter documents associated with a stakeholder'),
-      limit: z.number().optional().default(50).describe('Max results to return'),
+      limit: coerceInt('Max results to return').optional().default(50),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/documents', { params: input });
@@ -61,7 +62,7 @@ export const documentTools: ToolDefinition[] = [
         ])
         .optional()
         .describe('Filter by document type'),
-      limit: z.number().optional().default(20).describe('Max results to return'),
+      limit: coerceInt('Max results to return').optional().default(20),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/documents/search', { params: input });

package/src/tools/equityGrants.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { coerceInt, coerceFloat } from '../schema.js';
+import { type ToolDefinition } from '../types.js';
+
+export const equityGrantTools: ToolDefinition[] = [
+  {
+    name: 'list_equity_grants',
+    description:
+      'List all equity grants (options, RSAs, RSUs, etc.) for a company. ' +
+      'Use the `grantId` field from results for follow-up operations, not the `_id` field.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      limit: coerceInt('Max results to return').optional().default(50),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get('/api/v1/equity-grants', { params: input });
+      const grants = data.grants ?? data;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(grants, null, 2) }],
+      };
+    },
+  },
+  {
+    name: 'get_equity_grant',
+    description:
+      'Get details for a specific equity grant by ID. ' +
+      'Use the `grantId` field from `list_equity_grants`, not the `_id` field.',
+    inputSchema: z.object({
+      id: z
+        .string()
+        .describe('Grant ID — use the `grantId` field from list_equity_grants, not `_id`'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/equity-grants/${input.id}`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+  {
+    name: 'create_equity_grant',
+    description:
+      'Create a new equity grant for an employee or advisor. ' +
+      'Use the `grantId` field from list_equity_grants for follow-up operations, not the `_id` field.',
+    inputSchema: z.object({
+      companyId: z.string().describe('Company ID'),
+      employeeId: z
+        .string()
+        .describe('Stakeholder ID of the grantee — use the `row_id` from list_stakeholders'),
+      equityPlanId: z
+        .string()
+        .describe('Equity plan ID — use the `row_id` from list_equity_plans'),
+      grantType: z
+        .enum(['ISO', 'NSO', 'RSA', 'RSU', 'SAR', 'other'])
+        .describe('Type of equity grant'),
+      numberOfShares: coerceInt('Number of shares in this grant'),
+      grantDate: z.string().describe('Grant date in ISO 8601 format (YYYY-MM-DD)'),
+      vestingStartDate: z
+        .string()
+        .optional()
+        .describe('Vesting start date in ISO 8601 format (YYYY-MM-DD). Defaults to grantDate.'),
+      strikePrice: coerceFloat(
+        'Exercise/strike price per share in USD (required for options)'
+      ).optional(),
+      vestingSchedule: z
+        .object({
+          totalMonths: coerceInt('Total vesting period in months'),
+          cliffMonths: coerceInt('Cliff period in months'),
+        })
+        .optional()
+        .describe('Vesting schedule for this grant. Overrides the equity plan default.'),
+      notes: z.string().optional().describe('Free-text notes about this grant'),
+    }),
+    handler: async (input, client) => {
+      const { data: created } = await client.post('/api/v1/equity-grants', input);
+      const id = created.grantId ?? created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/equity-grants/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity grant created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity grant created (could not confirm persisted state — verify with get_equity_grant):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
+    },
+  },
+  {
+    name: 'update_equity_grant',
+    description:
+      'Update the status of an equity grant (e.g. approve, cancel, mark as exercised). ' +
+      'Use the `grantId` field from `list_equity_grants`, not the `_id` field.',
+    inputSchema: z.object({
+      id: z
+        .string()
+        .describe('Grant ID — use the `grantId` field from list_equity_grants, not `_id`'),
+      status: z
+        .enum(['pending', 'approved', 'active', 'exercised', 'cancelled', 'expired'])
+        .describe('New status for the grant'),
+    }),
+    handler: async (input, client) => {
+      const { id, ...body } = input;
+      const { data: updated } = await client.patch(
+        `/api/v1/equity-grants/${id}/status`,
+        body
+      );
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/equity-grants/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity grant updated:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity grant updated (could not confirm persisted state — verify with get_equity_grant):\n${JSON.stringify(updated, null, 2)}`,
+            },
+          ],
+        };
+      }
+    },
+  },
+  {
+    name: 'get_vesting_schedule',
+    description:
+      'Get the full vesting schedule for a specific equity grant — shows each vesting event, ' +
+      'cliff date, and cumulative shares vested over time. ' +
+      'Use the `grantId` field from `list_equity_grants`, not the `_id` field.',
+    inputSchema: z.object({
+      id: z
+        .string()
+        .describe('Grant ID — use the `grantId` field from list_equity_grants, not `_id`'),
+    }),
+    handler: async (input, client) => {
+      const { data } = await client.get(`/api/v1/equity-grants/${input.id}/vesting`);
+      return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    },
+  },
+];

package/src/tools/equityPlans.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceInt } from '../schema.js';
 import { type ToolDefinition } from '../types.js';
 
 export const equityPlanTools: ToolDefinition[] = [
@@ -8,7 +9,7 @@ export const equityPlanTools: ToolDefinition[] = [
       'List all equity plans (stock option plans, RSU plans, etc.) in the company.',
     inputSchema: z.object({
       companyId: z.string().optional().describe('Filter by company ID'),
-      limit: z.number().optional().default(50).describe('Max results to return'),
+      limit: coerceInt('Max results to return').optional().default(50),
     }),
     handler: async (input, client) => {
       const { data } = await client.get('/api/v1/equity-plans', { params: input });
@@ -20,9 +21,10 @@ export const equityPlanTools: ToolDefinition[] = [
   },
   {
     name: 'get_equity_plan',
-    description: 'Get details for a specific equity plan by ID.',
+    description:
+      'Get details for a specific equity plan by ID. Use the `row_id` field from `list_equity_plans`.',
     inputSchema: z.object({
-      id: z.string().describe('Equity plan ID'),
+      id: z.string().describe('Equity plan ID — use the `row_id` field from list_equity_plans'),
     }),
     handler: async (input, client) => {
       const { data } = await client.get(`/api/v1/equity-plans/${input.id}`);
@@ -37,10 +39,7 @@ export const equityPlanTools: ToolDefinition[] = [
       planType: z
         .enum(['ISO', 'NSO', 'RSA', 'RSU', 'SAR', 'other'])
         .describe('Type of equity plan'),
-      sharesReserved: z
-        .union([z.number(), z.string()])
-        .transform((v) => parseInt(String(v), 10))
-        .describe('Number of shares reserved for this plan'),
+      sharesReserved: coerceInt('Number of shares reserved for this plan'),
       companyId: z.string().describe('Company ID this plan belongs to'),
       expirationDate: z
         .string()
@@ -48,25 +47,35 @@ export const equityPlanTools: ToolDefinition[] = [
         .describe('Plan expiration date in ISO 8601 format (YYYY-MM-DD)'),
       defaultVestingSchedule: z
         .object({
-          totalMonths: z
-            .union([z.number(), z.string()])
-            .transform((v) => parseInt(String(v), 10))
-            .describe('Total vesting period in months'),
-          cliffMonths: z
-            .union([z.number(), z.string()])
-            .transform((v) => parseInt(String(v), 10))
-            .describe('Cliff period in months'),
+          totalMonths: coerceInt('Total vesting period in months'),
+          cliffMonths: coerceInt('Cliff period in months'),
         })
         .optional()
         .describe('Default vesting schedule for grants under this plan'),
     }),
     handler: async (input, client) => {
-      const { data } = await client.post('/api/v1/equity-plans', input);
-      return {
-        content: [
-          { type: 'text', text: `Equity plan created: ${JSON.stringify(data, null, 2)}` },
-        ],
-      };
+      const { data: created } = await client.post('/api/v1/equity-plans', input);
+      const id = created.row_id ?? created._id;
+      try {
+        const { data: confirmed } = await client.get(`/api/v1/equity-plans/${id}`);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity plan created:\n${JSON.stringify(confirmed, null, 2)}\n\nID for follow-up operations: ${id}`,
+            },
+          ],
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Equity plan created (could not confirm persisted state — verify with get_equity_plan):\n${JSON.stringify(created, null, 2)}`,
+            },
+          ],
+        };
+      }
     },
   },
 ];