# update\_idea

Update an idea. Requires mcp:write and the existing ConversionLab idea update policy.

Update an idea. Requires mcp:write and the existing ConversionLab idea update policy.

## Permissions

```json
{
  "ability": "mcp:write",
  "role": "The existing entity create/update policy must allow this user; write ability alone is insufficient.",
  "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.",
  "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant."
}
```

## Input

```json
{
  "properties": {
    "idea_id": {
      "description": "Idea ID",
      "type": "integer"
    },
    "project_id": {
      "description": "Optional new project ID",
      "type": "integer"
    },
    "name": {
      "description": "Optional idea name",
      "maxLength": 255,
      "type": "string"
    },
    "state_id": {
      "description": "Optional idea state ID",
      "type": "integer"
    },
    "source": {
      "description": "Optional source type",
      "type": "string"
    },
    "description": {
      "description": "Optional description",
      "type": "string"
    },
    "hypothesis": {
      "description": "Optional hypothesis",
      "type": "string"
    },
    "audience_ids": {
      "description": "Optional replacement audience IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "experiment_ids": {
      "description": "Optional replacement experiment IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "insight_ids": {
      "description": "Optional replacement insight IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "metric_ids": {
      "description": "Optional replacement metric IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "page_ids": {
      "description": "Optional replacement page IDs",
      "items": {
        "type": "integer"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "priority_values": {
      "description": "Optional prioritization values keyed by input variable, for example {\"impact\": 5, \"confidence\": 8, \"effort\": 2}",
      "type": [
        "object",
        "null"
      ]
    }
  },
  "type": "object",
  "required": [
    "idea_id"
  ]
}
```

## Output

```json
{
  "type": "object",
  "properties": {
    "updated": {
      "type": "boolean"
    },
    "found": {
      "type": "boolean"
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "project_id": {
              "type": [
                "integer",
                "null"
              ]
            },
            "name": {
              "type": "string"
            },
            "state_id": {
              "type": [
                "integer",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "audit",
                "insight",
                "experiment",
                "form",
                "api",
                null
              ]
            },
            "source_name": {
              "type": [
                "string",
                "null"
              ]
            },
            "priority_score": {
              "type": [
                "number",
                "string",
                "null"
              ],
              "description": "A decimal may be serialized as a string."
            },
            "created_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "updated_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "project": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "hypothesis": {
              "type": [
                "string",
                "null"
              ]
            },
            "priority_values": {
              "type": [
                "object",
                "array",
                "null"
              ],
              "additionalProperties": true,
              "items": true,
              "description": "Stored JSON values, usually keyed by the prioritization model variable."
            },
            "priority_details": {
              "type": [
                "object",
                "array",
                "null"
              ],
              "additionalProperties": true,
              "items": true
            },
            "state": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "audiences": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            },
            "experiments": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            },
            "insights": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            },
            "metrics": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            },
            "pages": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            }
          },
          "required": [
            "id",
            "project_id",
            "name",
            "state_id",
            "source",
            "source_name",
            "priority_score",
            "created_at",
            "updated_at",
            "description",
            "project",
            "hypothesis",
            "priority_values",
            "priority_details",
            "state",
            "audiences",
            "experiments",
            "insights",
            "metrics",
            "pages"
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "updated",
    "found",
    "data"
  ]
}
```

## Examples

### Request arguments

```json
{
  "idea_id": 101,
  "name": "Explain delivery times at checkout"
}
```

### Result

```json
{
  "updated": true,
  "found": true,
  "data": {
    "id": 101,
    "project_id": 1,
    "state_id": null,
    "name": "Explain delivery times at checkout",
    "source": "audit",
    "source_name": null,
    "priority_score": null,
    "created_at": "2026-01-15T12:00:00+00:00",
    "updated_at": "2026-01-15T12:00:00+00:00",
    "description": null,
    "hypothesis": null,
    "priority_values": null,
    "priority_details": null,
    "project": null,
    "state": null,
    "audiences": [],
    "experiments": [],
    "insights": [],
    "metrics": [],
    "pages": []
  }
}
```

### Request arguments

```json
{
  "idea_id": 101,
  "name": "Explain delivery times at checkout"
}
```

### Result

```json
{
  "updated": false,
  "found": false,
  "data": null
}
```

## Errors

```json
[
  {
    "status": 401,
    "description": "Missing, expired, or revoked bearer token."
  },
  {
    "status": 403,
    "description": "Missing MCP ability, team membership, plan entitlement, or user permission."
  },
  {
    "status": 404,
    "description": "The MCP server is disabled."
  },
  {
    "status": 429,
    "description": "Rate limited; honor Retry-After before retrying."
  },
  {
    "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call."
  }
]
```

An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See [authentication](https://conversionlab.app/docs/developer/authentication).