Settings
Tools for tenant settings — setting definitions, their categories, and current values.
This page covers 13 tools, all of them available on request rather than in the default tool list, and 2 destructive.
- Status — In the default tool list means the tool is one of the ~200 Aprimo advertises to every agent out of the box, so the agent discovers and calls it on its own. Available on request means the tool is registered and fully callable, but sits outside that default list — call it by name, or ask Aprimo to extend the list your tenant is served.
- Both statuses work identically when called. Status affects discovery, not capability or authorization.
- Visibility is not authorization. Every tool call executes as the authenticated user, and any tool can return an authorization error if that user lacks rights to the record, task, or file. See the MCP Tool Permission Map.
- Destructive tools are labelled as such. They delete or irreversibly overwrite data, and will not act unless the call sets both
confirmedandconfirmedDestructivetotrue. - Activity and Project labels vary by tenant. Where this page says Activity or Project, your tenant's own configured terminology is substituted at runtime.
Aprimo's MCP Server exposes far more tools than most MCP clients handle well — many degrade or truncate their tool list well below the full catalogue. Rather than let a client truncate arbitrarily, Aprimo advertises a curated set of roughly 200 tools covering the tasks customers most commonly automate. Everything outside that set remains fully supported and callable by name; it simply isn't offered up front. If your integration leans on a tool that is available on request, talk to your Aprimo Customer Success Manager about extending the advertised list for your tenant.
Tools at a Glance
| Tool | Status | What it does |
|---|---|---|
create_setting_category | On request | Creates a new Aprimo setting category. |
create_setting_definition | On request | Creates a new Aprimo setting definition. |
delete_setting_category | On request | Destructive. Permanently deletes an Aprimo setting category by id or by name. |
delete_setting_definition | On request | Destructive. Permanently deletes an Aprimo setting definition by id or by name. |
get_setting | On request | Gets one Aprimo setting's current value by its exact name (e.g. ".defaultRecordTitleField"). |
get_setting_category | On request | Gets one Aprimo setting category's detail (labels, tag, dates) by id or by name. |
get_setting_definition | On request | Gets one Aprimo setting definition's detail (data type, category, access flags, labels) by id or by name. |
list_setting_categories | On request | Lists the setting categories configured in Aprimo — named groupings used to organize related system settings for display (e.g. in Config Studio). |
list_setting_definitions | On request | Lists the setting definitions configured in Aprimo — the schema (name, data type, category) of each system setting. |
list_settings | On request | Lists Aprimo settings by name. |
update_setting | On request | Sets the value of an existing Aprimo setting by its exact name, at a specific scope (site/system/user/user group). |
update_setting_category | On request | Edits an existing Aprimo setting category by id or by name. |
update_setting_definition | On request | Edits an existing Aprimo setting definition by id or by name. |
create_setting_category
Available on request
Creates a new Aprimo setting category. This modifies data. Always confirm the name with the user before calling this tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name for the new setting category, exactly as the user stated it. |
labels | object (map of string) | No | Multi-language labels for the name of this setting category: a map of languageId (GUID) to label value. |
tag | string | No | Optional free-form tag for this setting category. Must be valid XML if provided. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string |
create_setting_definition
Available on request
Creates a new Aprimo setting definition. This modifies data. Always confirm the name, data type, and category with the user before calling this tool. Confirmed live against the tenant: DAM rejects a name containing spaces or a leading decimal point, and a name with any non-alphanumeric character ("The name of a setting should only contain alphanumeric characters, should not start with a decimal point and spaces are not allowed.") -- use a PascalCase-style name with no spaces/ punctuation. DAM also rejects a definition with no access-control flag set at all ("you need to specify at least one access control") -- set at least one of allowAnonymousAccess/allowSystemSetting/allowSiteSetting/allowUserSetting to true.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name for the new setting definition. DAM requires alphanumeric characters only -- no spaces, no punctuation, and it must not start with a decimal point. |
dataType | string | Yes | The setting's data type. One of: text, boolean, numeric, datetime, xml, role, reference, encryptedtext. |
categoryId | string | Yes | The id (GUID) of the setting category this definition belongs to. |
allowAnonymousAccess | boolean | No | When true, this setting can be read without authentication. Defaults to false. |
allowSystemSetting | boolean | No | When true, this setting can be configured at the system level. |
allowSiteSetting | boolean | No | When true, this setting can be configured at the site level. |
allowUserSetting | boolean | No | When true, this setting can be configured per user. |
roleRequiredForChange | string | No | Optional name of the role required to change settings of this definition. |
labels | object (map of string) | No | Multi-language labels for the name of this setting definition: a map of languageId (GUID) to label value. |
tag | string | No | Optional free-form tag for this setting definition. Must be valid XML if provided. |
helpUrl | string | No | Optional URL to help documentation for this setting definition. |
userGroupSettingMode | string | No | Optional algorithm for computing the effective value across user-group settings. One of: None, MaximumValue, MinimumValue, Manual, FirstValue. |
defaultValue | string | No | Optional default value for this setting definition, as a plain string. For dataType 'boolean' provide "true"/"false"; for 'numeric' provide a whole number — both are sent to Aprimo as their native JSON type, not a quoted string. Every other dataType (including 'datetime', as an ISO-8601 string) is sent as-is. |
regularExpression | string | No | Optional regular expression used to validate the value (text/encryptedtext data types). |
range | string | No | Optional range of allowed values, e.g. "1-255" (numeric data type). |
schema | string | No | Optional schema used to validate the value (xml data type). |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string |
delete_setting_category
Available on request · Destructive
Permanently deletes an Aprimo setting category by id or by name. This cannot be undone. Requires both confirmed=true and confirmedDestructive=true, after explicitly confirming the exact setting category with the user.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingCategoryId | string | No | The setting category id (GUID) to delete. Provide this or name, not both. |
name | string | No | The setting category's exact name (case-insensitive). Provide this or settingCategoryId, not both. |
confirmed | boolean | No | Must be true to proceed. Set to false (or omit) to get a confirmation gate error, then call again with confirmed=true after the user has explicitly confirmed the exact setting category. |
confirmedDestructive | boolean | No | Must also be true (in addition to confirmed) — deleting a setting category is permanent and cannot be undone. Set only after stating the exact setting category to the user and getting explicit go-ahead. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string (optional) | |
deleted | boolean |
This tool deletes or irreversibly overwrites data in the live tenant; the change cannot be rolled back through the API. It will not act unless the call sets both confirmed and confirmedDestructive to true.
delete_setting_definition
Available on request · Destructive
Permanently deletes an Aprimo setting definition by id or by name. This cannot be undone. Requires both confirmed=true and confirmedDestructive=true, after explicitly confirming the exact setting definition with the user.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingDefinitionId | string | No | The setting definition id (GUID) to delete. Provide this or name, not both. |
name | string | No | The setting definition's exact name (case-insensitive). Provide this or settingDefinitionId, not both. |
confirmed | boolean | No | Must be true to proceed. Set to false (or omit) to get a confirmation gate error, then call again with confirmed=true after the user has explicitly confirmed the exact setting definition. |
confirmedDestructive | boolean | No | Must also be true (in addition to confirmed) — deleting a setting definition is permanent and cannot be undone. Set only after stating the exact setting definition to the user and getting explicit go-ahead. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string (optional) | |
deleted | boolean |
This tool deletes or irreversibly overwrites data in the live tenant; the change cannot be rolled back through the API. It will not act unless the call sets both confirmed and confirmedDestructive to true.
get_setting
Available on request
Gets one Aprimo setting's current value by its exact name (e.g. ".defaultRecordTitleField"). Not its category (get_setting_category) or its definition/schema (get_setting_definition). Optionally reads it at a specific scope (site/system/user/user group) rather than the caller's own effective value.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingName | string | Yes | The setting's exact name, e.g. ".defaultRecordTitleField". |
scope | string | No | Optional scope to read the setting at. One of: Site, System, User, UserGroup. Omit to read the caller's own effective value. |
scopeId | string | No | The id (GUID) of the entity the scope applies to (e.g. a user group id when scope is UserGroup). Required together with scope, when scope needs one. |
Returns:
| Field | Type | Description |
|---|---|---|
name | string | |
value | string (optional) |
get_setting_category
Available on request
Gets one Aprimo setting category's detail (labels, tag, dates) by id or by name. Use after list_setting_categories, or directly when the user names the category.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingCategoryId | string | No | The setting category id (GUID). Provide this or name, not both. |
name | string | No | The setting category's exact name (case-insensitive). Provide this or settingCategoryId, not both. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
labels | array of SettingLabelPayload | |
labels[].value | string (optional) | |
labels[].languageId | string | |
tag | string (optional) | |
createdOn | string (optional) | |
modifiedOn | string (optional) |
get_setting_definition
Available on request
Gets one Aprimo setting definition's detail (data type, category, access flags, labels) by id or by name. Use after list_setting_definitions, or directly when the user names the definition.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingDefinitionId | string | No | The setting definition id (GUID). Provide this or name, not both. |
name | string | No | The setting definition's exact name (case-insensitive). Provide this or settingDefinitionId, not both. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
dataType | string (optional) | |
categoryId | string (optional) | |
helpUrl | string (optional) | |
userGroupSettingMode | string (optional) | |
labels | array of SettingLabelPayload | |
labels[].value | string (optional) | |
labels[].languageId | string | |
allowSystemSetting | boolean (optional) | |
allowUserSetting | boolean (optional) | |
roleRequiredForChange | string (optional) | |
defaultValue | object (optional) | |
createdOn | string (optional) | |
modifiedOn | string (optional) |
list_setting_categories
Available on request
Lists the setting categories configured in Aprimo — named groupings used to organize related system settings for display (e.g. in Config Studio). Use when the user asks what setting categories exist, or to look up a category's id/exact name before calling get_setting_category, update_setting_category, or delete_setting_category by name.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | Optional filter expression (DAM query syntax), e.g. "ModifiedOn in today". Omit to list every setting category. |
sort | string | No | Optional sort expression, e.g. "createdOn". Omit for the endpoint's default order. |
skip | integer | No | Number of items to skip, for paging. Defaults to 0. |
take | integer | No | Maximum number of items to return. Omit for the endpoint's default page size. |
Returns:
| Field | Type | Description |
|---|---|---|
count | integer | |
items | array of SettingCategoryPayload | |
items[].id | string | |
items[].name | string | |
items[].labels | array of SettingLabelPayload | |
items[].labels[].value | string (optional) | |
items[].labels[].languageId | string | |
items[].tag | string (optional) | |
items[].createdOn | string (optional) | |
items[].modifiedOn | string (optional) |
list_setting_definitions
Available on request
Lists the setting definitions configured in Aprimo — the schema (name, data type, category) of each system setting. Use when the user asks what setting definitions exist, or to look up a definition's id/exact name before calling get_setting_definition, update_setting_definition, or delete_setting_definition by name.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | Optional filter expression (DAM query syntax), e.g. "ModifiedOn in today". Omit to list every setting definition. |
sort | string | No | Optional sort expression, e.g. "createdOn". Omit for the endpoint's default order. |
skip | integer | No | Number of items to skip, for paging. Defaults to 0. |
take | integer | No | Maximum number of items to return. Omit for the endpoint's default page size. |
Returns:
| Field | Type | Description |
|---|---|---|
count | integer | |
items | array of SettingDefinitionPayload | |
items[].id | string | |
items[].name | string | |
items[].dataType | string (optional) | |
items[].categoryId | string (optional) | |
items[].helpUrl | string (optional) | |
items[].userGroupSettingMode | string (optional) | |
items[].labels | array of SettingLabelPayload | |
items[].labels[].value | string (optional) | |
items[].labels[].languageId | string | |
items[].allowSystemSetting | boolean (optional) | |
items[].allowUserSetting | boolean (optional) | |
items[].roleRequiredForChange | string (optional) | |
items[].defaultValue | object (optional) | |
items[].createdOn | string (optional) | |
items[].modifiedOn | string (optional) |
list_settings
Available on request
Lists Aprimo settings by name. Only settings the caller may see are returned (DAM's own allowlist/whitelist mechanism silently omits the rest — this never fails with an error for that reason). Provide exact setting names (e.g. ".defaultRecordTitleField") — there is no browse-all or partial-match query for settings.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
names | . Required — the endpoint has no browse-all for settings and 400s if this is omitted or empty.")] List<string> | Yes | Exact setting names to fetch, e.g. [".recordFieldViewList", ".userFieldViewList"]. Required — the endpoint has no browse-all for settings and 400s if this is omitted or empty. |
skip | integer | No | Number of items to skip, for paging. Defaults to 0. |
take | integer | No | Maximum number of items to return. Omit for the endpoint's default page size. |
Returns:
| Field | Type | Description |
|---|---|---|
count | integer | |
items | array of SettingPayload | |
items[].name | string | |
items[].value | string (optional) |
update_setting
Available on request
Sets the value of an existing Aprimo setting by its exact name, at a specific scope (site/system/user/user group). This modifies data. Always confirm the exact setting name, scope, and new value with the user before calling this tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingName | string | Yes | The setting's exact name to update, e.g. ".defaultRecordTitleField". |
value | string | Yes | The new value for this setting, exactly as the user stated it. |
scope | string | Yes | Scope to set the setting at. One of: Site, System, User, UserGroup. Required -- the endpoint has no caller-default scope and 400s with "The setting's scope property should be set." if this is omitted. |
scopeId | string | No | The id (GUID) of the entity the scope applies to (e.g. a user group id when scope is UserGroup). Required together with scope, when scope needs one. |
Returns:
| Field | Type | Description |
|---|---|---|
name | string | |
value | string | |
scope | string (optional) | |
scopeId | string (optional) |
update_setting_category
Available on request
Edits an existing Aprimo setting category by id or by name. Only the fields provided are changed — omitted fields keep their current value. This modifies data. Always confirm the exact setting category and the new values with the user before calling this tool.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingCategoryId | string | No | The setting category id (GUID) to edit. Provide this or name, not both. |
name | string | No | The setting category's current name (case-insensitive), used to look it up. Provide this or settingCategoryId, not both. |
newName | string | No | New name for the setting category. Omit to leave the name unchanged. |
labels | object (map of string) | No | Label values to set: a map of languageId (GUID) to label value. Only the languages provided are changed. |
tag | string | No | New free-form tag. Must be valid XML if provided. Omit to leave it unchanged. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string (optional) |
update_setting_definition
Available on request
Edits an existing Aprimo setting definition by id or by name. Only the fields provided are changed — omitted fields keep their current value. This modifies data. Always confirm the exact setting definition and the new values with the user before calling this tool. Note: the data type cannot be changed after creation.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
settingDefinitionId | string | No | The setting definition id (GUID) to edit. Provide this or name, not both. |
name | string | No | The setting definition's current name (case-insensitive), used to look it up. Provide this or settingDefinitionId, not both. |
newName | string | No | New name for the setting definition. Omit to leave the name unchanged. |
categoryId | string | No | New setting category id (GUID). Omit to leave it unchanged. |
defaultValue | string | No | New default value (as a plain string). Omit to leave it unchanged. |
regularExpression | string | No | New regular expression used to validate the value. Omit to leave it unchanged. |
range | string | No | New range of allowed values, e.g. "1-255". Omit to leave it unchanged. |
schema | string | No | New schema used to validate the value. Omit to leave it unchanged. |
labels | object (map of string) | No | Label values to set: a map of languageId (GUID) to label value. Only the languages provided are changed. |
allowSystemSetting | boolean | No | New value for whether this setting can be configured at the system level. Omit to leave it unchanged. |
allowUserSetting | boolean | No | New value for whether this setting can be configured per user. Omit to leave it unchanged. |
roleRequiredForChange | string | No | New name of the role required to change settings of this definition. Omit to leave it unchanged. |
userGroupSettingMode | string | No | New algorithm for computing the effective value across user-group settings. One of: None, MaximumValue, MinimumValue, Manual, FirstValue. Omit to leave it unchanged. |
helpUrl | string | No | New URL to help documentation. Omit to leave it unchanged. |
tag | string | No | New free-form tag. Must be valid XML if provided. Omit to leave it unchanged. |
Returns:
| Field | Type | Description |
|---|---|---|
id | string | |
name | string (optional) |
Related
- Aprimo MCP Server — configuration, connection details, and authentication
- MCP Tool Permission Map — the Aprimo permissions that make each tool visible to your agent
- REST API vs. MCP — choosing the right integration approach for your agent