mcp_manage_choice

Summary

Field	Value
Tool name	manage_choice
MCP title	Manage global option sets (choices)
Category	basic
Implementation	DynamicsCrm.DevKit.Cli/Mcp/Tools/ManageChoiceTool.cs
Estimated token count	~914 tokens (tools/list tool JSON, o200k_base, measured 2026-06-18)
Last verified	2026-06-18

MCP Tool Description (Exact)

Global option sets (choices/picklists) — list/detail/create/update. Required: list=(none); detail=optionset_name (logical name OR display name — display name resolved automatically); create=display_name+options+solution_name (optionset_name optional — auto-derived from publisher prefix + compact lowercase display_name if omitted; if provided it MUST start with the solution publisher prefix or an error is returned); update=optionset_name+at least one of (display_name, description, add_options, update_options, remove_options). For local picklists use get_tables. list/detail never publish. create and delete-only update do not issue a publish request because Dataverse auto-publishes newly created/deleted customizations. Other updates always publish only the affected option set. list supports optional filter= to search by name or display name (contains, case-insensitive).

OPTION VALUES: solution_name is REQUIRED for create and for label-only add_options — if not provided by the user, ask; never search or guess. Pass options/add_options as label-only ('Draft;Confirmed'). For update_options use 'OldLabel:NewLabel;...' pairs. For remove_options use label names ('Draft,Cancelled') — labels are resolved to values automatically.

OPTION COLORS: Use option_colors='Label:#RRGGBB;...' or 'value:#RRGGBB;...' to assign hex colors to option items. Applies to create and update. Labels are resolved case-insensitively. Example: 'Draft:#808080;Paid:#008000'. Color keys must resolve to existing options; duplicates are rejected.

WHEN TO USE:
- Resolve label for picklist fields in FetchXML / query results
- Create a global choice for upsert_column to reference
- Add, rename, or remove option values on an existing global choice

SAFETY:
- remove_options is destructive and cannot be undone

Parameters

Name	Type	Required	Default	Description
action	string	Yes	-	'list', 'detail', 'create', 'update'.
optionset_name	string	No	""	Logical name OR display name. Required except list and create. For detail/update: Display Name contains is resolved first, then logical name contains; ambiguity returns an error. For create: if omitted, auto-derived as '{publisher_prefix}_{compact_lowercase_display_name}' (portal default, e.g. 'devkit_invoicestatus'); if provided, must start with the solution publisher prefix (e.g. 'devkit_invoicestatus') — error returned otherwise.
display_name	string	No	""	Required for create. Optional for update. For list: used as a filter (contains match on name and display name, case-insensitive).
filter	string	No	""	list only. Optional keyword filter applied to both logical name and display name (contains, case-insensitive). Shorthand alternative to display_name for filtering.
description	string	No	""	Optional for create/update.
options	string	No	""	Create only. Label-only 'Draft;Confirmed'. Values are auto-assigned from the solution publisher's customizationoptionvalueprefix. solution_name is required.
add_options	string	No	""	Update only. Label-only 'NewLabel' (value auto-assigned from solution publisher prefix, next sequential) or 'value:label;...' pairs to add.
update_options	string	No	""	Update only. 'OldLabel:NewLabel;...' pairs to rename. Labels are resolved to values automatically.
remove_options	string	No	""	Update only. Comma-separated label names to remove (e.g. 'Draft,Cancelled'). Irreversible.
solution_name	string	No	""	Required for create. Required for label-only add_options. Used to resolve the publisher prefix for auto-generating option values.
option_colors	string	No	""	Optional for create/update. Semicolon-separated color mappings. Use 'Label:#RRGGBB' or 'value:#RRGGBB'. Labels are resolved case-insensitively. Example: 'Draft:#808080;Paid:#008000'.

Input Schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "'list', 'detail', 'create', 'update'."
    },
    "optionset_name": {
      "type": "string",
      "description": "Logical name OR display name. Required except list and create. For detail/update: Display Name contains is resolved first, then logical name contains; ambiguity returns an error. For create: if omitted, auto-derived as '{publisher_prefix}_{compact_lowercase_display_name}' (portal default, e.g. 'devkit_invoicestatus'); if provided, must start with the solution publisher prefix (e.g. 'devkit_invoicestatus') — error returned otherwise.",
      "default": ""
    },
    "display_name": {
      "type": "string",
      "description": "Required for create. Optional for update. For list: used as a filter (contains match on name and display name, case-insensitive).",
      "default": ""
    },
    "filter": {
      "type": "string",
      "description": "list only. Optional keyword filter applied to both logical name and display name (contains, case-insensitive). Shorthand alternative to display_name for filtering.",
      "default": ""
    },
    "description": {
      "type": "string",
      "description": "Optional for create/update.",
      "default": ""
    },
    "options": {
      "type": "string",
      "description": "Create only. Label-only 'Draft;Confirmed'. Values are auto-assigned from the solution publisher's customizationoptionvalueprefix. solution_name is required.",
      "default": ""
    },
    "add_options": {
      "type": "string",
      "description": "Update only. Label-only 'NewLabel' (value auto-assigned from solution publisher prefix, next sequential) or 'value:label;...' pairs to add.",
      "default": ""
    },
    "update_options": {
      "type": "string",
      "description": "Update only. 'OldLabel:NewLabel;...' pairs to rename. Labels are resolved to values automatically.",
      "default": ""
    },
    "remove_options": {
      "type": "string",
      "description": "Update only. Comma-separated label names to remove (e.g. 'Draft,Cancelled'). Irreversible.",
      "default": ""
    },
    "solution_name": {
      "type": "string",
      "description": "Required for create. Required for label-only add_options. Used to resolve the publisher prefix for auto-generating option values.",
      "default": ""
    },
    "option_colors": {
      "type": "string",
      "description": "Optional for create/update. Semicolon-separated color mappings. Use 'Label:#RRGGBB' or 'value:#RRGGBB'. Labels are resolved case-insensitively. Example: 'Draft:#808080;Paid:#008000'.",
      "default": ""
    }
  },
  "required": [
    "action"
  ]
}

Related MCP Resources

This tool does not require any MCP resources.

When To Use

• Resolve label for picklist fields in FetchXML / query results
• Create a global choice for upsert_column to reference
• Add, rename, or remove option values on an existing global choice

Notes

• SAFETY: remove_options is destructive and cannot be undone
• OPTION VALUES: solution_name is REQUIRED for create and for label-only add_options — if not provided by the user, ask; never search or guess. Pass options/add_options as label-only ('Draft;Confirmed'). For update_options use 'OldLabel:NewLabel;...' pairs. For remove_options use label names ('Draft,Cancelled') — labels are resolved to values automatically.
• OPTION COLORS: Use option_colors='Label:#RRGGBB;...' or 'value:#RRGGBB;...' to assign hex colors to option items. Applies to create and update. Labels are resolved case-insensitively. Example: 'Draft:#808080;Paid:#008000'. Color keys must resolve to existing options; duplicates are rejected.

Example

{
  "action": "string"
}

Output

Returns CallToolResult from the MCP server. The response content and structured fields follow the tool implementation and model returned by ManageChoiceTool.manage_choice.

Prompt Examples

• "Create a global choice for invoice status with Draft, Confirmed, and Paid options."
• "Add a Cancelled option to this global choice and publish the affected option set."
• "Rename these choice labels and assign colors to each option."