fix(monaco): reject a stage key and a stage ID together on opportunity writes

apps/docs/content/docs/integrations/monaco.mdx

@@ -794,7 +794,7 @@ Create a Monaco opportunity on an existing account, optionally setting its pipel
 | `accountId` | string | Yes | ID of the account to associate the opportunity with |
 | `pipelineId` | string | No | Pipeline to create the opportunity in \(see List Pipelines\). If omitted, the organization's default pipeline is used. |
 | `stage` | string | No | Stage key for the opportunity within its pipeline \(up to 64 characters; see List Pipelines\). If omitted, the opportunity is placed in the first stage of that pipeline. |
-| `stageId` | string | No | Stage ID \(from List Pipelines\), instead of a stage key. It names the pipeline too, so a pipeline ID, if given, must be that stage's pipeline. |
+| `stageId` | string | No | Stage ID \(from List Pipelines\), instead of a stage key; provide either stage or stageId, not both. It names the pipeline too, so a pipeline ID, if given, must be that stage's pipeline. |
 | `ownerUserId` | string | No | User ID to assign as the opportunity owner |
 | `amount` | number | No | Estimated value as a decimal amount of the currency \(e.g. 50000.25\). Set together with currencyCode. |
 | `currencyCode` | string | No | ISO 4217 currency code of the estimated value \(e.g. USD\), up to 8 characters. Set together with amount. |
@@ -852,7 +852,7 @@ Update a Monaco opportunity: rename it, change its owner, move it to another sta
 | `name` | string | No | New name of the opportunity |
 | `pipelineId` | string | No | Pipeline to move the opportunity to \(see List Pipelines\). The stage key then names a stage in that pipeline; if no stage is given, an open opportunity lands on the pipeline's first active stage and a closed one on its first closed stage with the same outcome. If omitted, the opportunity stays in its pipeline. |
 | `stage` | string | No | Stage key for the opportunity within its pipeline \(up to 64 characters; see List Pipelines\) |
-| `stageId` | string | No | Stage ID \(from List Pipelines\), instead of a stage key. A stage of the opportunity's own pipeline changes its stage; a stage of another pipeline moves the opportunity there. |
+| `stageId` | string | No | Stage ID \(from List Pipelines\), instead of a stage key; provide either stage or stageId, not both. A stage of the opportunity's own pipeline changes its stage; a stage of another pipeline moves the opportunity there. |
 | `ownerUserId` | string | No | User ID to assign as the opportunity owner |
 | `amount` | number | No | Estimated value as a decimal amount of the currency \(e.g. 50000.25\). Set together with currencyCode. |
 | `currencyCode` | string | No | ISO 4217 currency code of the estimated value \(e.g. USD\), up to 8 characters. Set together with amount. |

apps/sim/tools/monaco/create_opportunity.ts

@@ -60,7 +60,7 @@ export const monacoCreateOpportunityTool: ToolConfig<
       required: false,
       visibility: 'user-or-llm',
       description:
-        "Stage ID (from List Pipelines), instead of a stage key. It names the pipeline too, so a pipeline ID, if given, must be that stage's pipeline.",
+        "Stage ID (from List Pipelines), instead of a stage key; provide either stage or stageId, not both. It names the pipeline too, so a pipeline ID, if given, must be that stage's pipeline.",
     },
     ownerUserId: {
       type: 'string',

apps/sim/tools/monaco/update_opportunity.ts

@@ -61,7 +61,7 @@ export const monacoUpdateOpportunityTool: ToolConfig<
       required: false,
       visibility: 'user-or-llm',
       description:
-        "Stage ID (from List Pipelines), instead of a stage key. A stage of the opportunity's own pipeline changes its stage; a stage of another pipeline moves the opportunity there.",
+        "Stage ID (from List Pipelines), instead of a stage key; provide either stage or stageId, not both. A stage of the opportunity's own pipeline changes its stage; a stage of another pipeline moves the opportunity there.",
     },
     ownerUserId: {
       type: 'string',

apps/sim/tools/monaco/utils.ts

@@ -747,6 +747,9 @@ export function buildMonacoOpportunityWriteBody(params: {
     const trimmed = value?.trim()
     if (trimmed) body[key] = trimmed
   }
+  if (body.stage && body.stage_id) {
+    throw new Error('Provide either stage or stageId, not both')
+  }
   if (params.notes?.trim()) body.notes = params.notes
 
   const currencyCode = params.currencyCode?.trim()

apps/sim/tools/monaco/write_bodies.test.ts

@@ -1,6 +1,7 @@
 /**
  * Request bodies whose shape decides what Monaco changes: an empty filter group seeds an
- * audience with every contact, and an empty tag list on PATCH clears a record's tags.
+ * audience with every contact, an empty tag list on PATCH clears a record's tags, and an
+ * opportunity takes a stage key or a stage ID, never both.
  */
 import { describe, expect, it } from 'vitest'
 import { monacoCreateAudienceTool } from '@/tools/monaco/create_audience'
@@ -50,3 +51,15 @@ describe('Monaco PATCH tags', () => {
     })
   })
 })
+
+describe('Monaco opportunity stage', () => {
+  it('rejects a stage key and a stage ID together', () => {
+    expect(() =>
+      requestBody(monacoUpdateOpportunityTool, {
+        opportunityId: 'o-1',
+        stage: 'proposal',
+        stageId: 's-1',
+      })
+    ).toThrow('Provide either stage or stageId, not both')
+  })
+})