System tools for Content Management System (SaaS)

25 min

Mark (Optimizely Agent Platform) includes system tools that Optimizely provides and maintains. System tools are built-in features that help Mark take action. Each tool performs a specific task, such as creating a campaign, uploading files, or generating images. Think of tools like attachments on a Swiss Army knife. Each one has a distinct purpose that helps you get work done.

In addition to the system tools available in Mark, Optimizely Content Management System (CMS) (SaaS) includes a set of system tools to help you with CMS-related tasks, such as managing content.

Note

Ask Mark what tools it has at any time. For example, enter "Please list the tools you have with a brief description of what they do and the parameters" into Mark chat.

Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts for calling the tool. If you do not provide a required parameter, Mark prompts you for it.

Content types

Content types act as blueprints for your content, specifying what kind of data each piece of content can hold. For example, a "News Article" content type might have fields for title, body, author, and publish date.

Important

New content types must follow the same conventions (for example, naming conventions) as existing content types. Use the cms_list_content_types tool to get existing content types and the cms_get_content_type_details tool to get details, including all properties for a specific content type.

If you are creating multiple content types, always create and register content types with baseType: "_component" first. This ensures that other content types can properly reference them.

The group field for a property must reference an existing property group. Use the cms_list_property_groups tool to list existing property groups or the cms_create_property_group tool to create one. See the Property groups section.

When to use

Define a new structure for a specific type of content you want to manage in your CMS (SaaS) instance.

Create content models for pages, experiences, components, or sections.

Standardize the properties and behaviors of content items across your website or application.

Parameters

Key – A machine-readable key that must be unique in your instance of CMS (SaaS) (for example, 'NewsArticle', 'HeroComponent').

DisplayName – The human-readable name of the content type (for example, 'News Article', 'Hero').

Description – A brief explanation of the content type's purpose (for example, 'Used to display news articles on a website').

BaseType – The base type of the content type. Valid values include the following:

_page – For content that has a fixed position in your site structure and a specific URL (for example, an "About Us" page).

_experience – Similar to _page, but includes a dynamic area where editors can add components and sections.

_component – For smaller, reusable content structures that are embedded within other content types (for example, a "Hero Banner" component). Components are not standalone pages.

_section – An extension of _component that lets editors add components in a grid structure. Sections can only be used within experiences.

_media – For generic media assets.

_image – For image assets.

_video – For video assets.

Properties – A JSON object defining the fields (properties) of your content type. Each property has its own displayName, type, localized status, required status, group, sortOrder, and indexingType. The following is an example:

      {
          "Title": {
              "displayName": "Title of the page",
              "type": "string",
              "localized": true,
              "required": true,
              "group": "Information",
              "sortOrder": 10,
              "indexingType": "searchable"
          }
      }

(Optional) CompositionBehaviors – Applicable only to _component base types. Specifies where the component can be used. Valid values are 'sectionEnabled' (usable within an experience) and 'elementEnabled' (usable within a section).

(Optional) MayContainTypes – Applicable only to _page and _experience base types. Specifies which other content types can be placed as children beneath an instance of this content type in the site structure.

Example prompts

Create a content type for "Blog Post" with fields for title, author, and content.

I need a new component content type called "CallToAction" that has a headline, description, and a link.

Define an experience content type named "LandingPage" that can contain various components.

Create a content type for "ProductReview" that includes fields for rating, reviewer name, and review text.

Non-disruptive updates – The cms_update_content_type tool prioritizes the integrity of your existing content. If an update would cause a BreakingChanges error (for example, changing a field's type in a way that would invalidate existing content), the operation fails. In such cases, if the content type was initially created by you, you might need to consider deleting it (if it has no content instances) and recreating it with the desired properties.

Property groups – Any group you specify for a property must reference an existing property group. You can use the cms_list_property_groups tool to see available groups or cms_create_property_group tool to create one. See the Property groups section.

Partial updates – You only need to provide the properties you intend to update. Any properties not included in your request remain unchanged.

When to use

Modify specific properties of an existing content type (for example, change the displayName of a field, update its description, or adjust its maxLength).

Add new properties to an existing content type.

Update the baseType, CompositionBehaviors, Description, DisplayName, or MayContainTypes of a content type, provided the changes are non-disruptive.

Properties

Key – The machine-readable key of the content type you want to update.

(Optional) DisplayName – The new human-readable name for the content type.

(Optional) Description – The new description for the content type.

(Optional) BaseType – The new base type for the content type. Valid values include the following:

_page

_experience

_component

_section.

_media

_image

_video

(Optional) Properties – A JSON object containing the properties you want to update or add. For example, the following JSON changes the display name of an existing Title property:

      {
          "Title": {
              "displayName": "Title of the page"
          }

Content items

Blueprints

Blueprints are reusable templates that capture a layout structure and default property values. Editors create blueprints with Save as Blueprint in Visual Builder. Use these tools to find a blueprint and see what it contains. To create content from a blueprint, use the Blueprint parameter on the cms_update_content_item tool.

Styles

Styles (also called display templates) control how content is rendered in the Visual Builder. Each style (template) is associated with exactly one type: a composition node type (for example, section, row, or column), a content base type (for example, page or component), or a specific content type key.

Idea Lab tools

Note The Idea Lab tools are available for CMS (SaaS) and Content Marketing Platform (CMP).

Optimizely Graph tools

Note

The Optimizely Graph tools are available for CMS (SaaS), CMS 12 (PaaS), and CMS 13 (Paas) for users who also have Optimizely Graph.

When to use

List pinned results or pinned result collections in Optimizely Graph.

Add a pinned result collection and associate search phrases with a target content key.

Update a pinned result or a collection to change the priority or the active status.

Remove a pinned result or a pinned result collection.

Retrieve pinned results in a collection with filtering, sorting, and pagination.

Parameters

operation_id – The unique identifier for the pinned result operation.

0 – List all pinned results.

1 – List all pinned result collections.

2 – List pinned results in specific collection.

3 – Add or update pinned result collection.

4 – Remove pinned result collection.

5 – Add or update pinned result.

6 – Remove pinned result.

(Optional) collection_id – The unique identifier for the pinned result collection. Use this together with operation_id 2 or 3 (in case of update, leave blank in case of add), or 4.

(Optional) isActive – Specifies if the pinned result collection should be active. Use this together with operation_id 5.

(Optional) key – The key of the pinned result collection. Use this together with operation_id 5.

(Optional) language – The language the item will be added for. Use this together with operation_id 5.

(Optional) limit – Maximum number of items to return. Use this together with operation_id 0 and 2.

(Optional) offset – Number of items to skip for pagination. Use this together with operation_id 0 and 2.

(Optional) phrase – Filter items by phrase. Use this together with operation_id 0 and 2.

(Optional) phrases – The phrases to add. Use this together with operation_id 5.

(Optional) pinned_result_id – The unique identifier for the pinned result. Use this together with operation_id 5 (in case of update, leave blank in case of add), or 6.

(Optional) priority – The priority for the item. Use this together with operation_id 5.

(Optional) sort – Sort field (for example, "priority" or "created"). Use this together with operation_id 0 and 2.

(Optional) targetKey – The target key for the pinned result item. Use this together with operation_id 5.

(Optional) title – The title of the pinned result collection. Use this together with operation_id 5.

Example prompts

Show me the pinned result collections in Optimizely Graph.

Create a pinned result collection with the phrase "winter sale" that targets the key winter-promo-page.

Update the pinned result with ID 42 and set the priority to 1.

List the pinned results in collection 15, sorted by priority.

Remove the pinned result collection with ID 7.

Property groups

Property groups are used to organize properties within content types, making the content editing interface more structured.

Taxonomy

The taxonomy tools manage categories, the hierarchical terms that editors assign to content to classify and organize it in your CMS (SaaS) instance. Requests that use the words categories, labels, or tags reach these tools. The tools do not read or set the separate Tags field on a content item.

Note

The taxonomy tools require CMS administrator rights.

Note

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.

System tools for Content Management System (SaaS)

Content types

cms_list_content_types – Gets a list of content types, excluding properties, from CMS (SaaS). This tool provides an overview of the available content structures you can use, without providing the full details of each property.

cms_get_content_type_details – Gets the full details of a content type, including properties, from CMS (SaaS).

cms_create_content_type – Creates a new content type in CMS (SaaS).

cms_delete_content_type – Performs a non-disruptive deletion of a content type in CMS (SaaS).

cms_update_content_type – Updates an existing content type in CMS (SaaS) using a JSON Merge Patch algorithm.

Content items

cms_create_content_item – Creates a new empty content instance in CMS (SaaS) based on an existing content type.

cms_create_content_variation – Creates a content variation (alternative version) for an existing page or experience content item.

cms_get_content_data – Retrieves CMS (SaaS) content data for a specific content item.

cms_get_content_preview_url – Generates a preview URL with authentication tokens for viewing draft or published content in configured preview applications.

cms_delete_content_item – Deletes a content item from CMS (SaaS) using its unique content key.

cms_publish_content_item – Publishes a specific content version in CMS (SaaS), making it visible to site visitors.

cms_update_content_item – Updates the value for any property of a content item using a JSON Merge Patch algorithm.

cms_upload_media – Uploads an image, video, or document to the CMS (SaaS) media library from a URL or a file attached in Mark chat﻿.

Blueprints

cms_list_blueprints – Lists the blueprints available in CMS (SaaS), with optional filters for name and content type.

cms_get_blueprint – Gets the full definition of one or more blueprints, including the layout structure and default property values.

Styles

cms_list_display_templates – Lists all styles (display templates) registered in the CMS, including their type association, default state, and a summary of their settings.

cms_get_display_template – Gets the full details of a style (display template) by its key, including all settings and choices.

Idea Lab tools

get_idealab_domain_competition – Returns Idea Lab domain organic competition data.

get_idealab_domain_keywords– Returns Idea Lab domain organic competition data.

get_idealab_keyword_infos – Returns Idea Lab SEO keyword information.

get_idealab_keyword_keyword_questions – Returns common questions for an Idea Lab SEO keyword in a given country. This is highly valuable for content creation, FAQ development, and understanding user intent.

get_idealab_keyword_related_keywords – Returns related keywords that are semantically related to a given keyword in a specific country. This helps in expanding keyword research and discovering new content opportunities.

Optimizely Graph tools

graph_content_type_schema – Use as your starting point for understanding the content structure within your Optimizely Graph instance. The tool lets you and Mark﻿ discover available content types and their fields, which is crucial for constructing accurate GraphQL queries.

graph_content_graphql_executor – Execute custom GraphQL queries against your Optimizely Graph instance. You can retrieve specific content items, filter results, sort, and get aggregated data (facets).

graph_content_search_tool – Use as a simpler alternative for searching content in Optimizely Graph when constructing complex GraphQL queries might be excessive. It lets you search for content based on a search phrase across a specified content type.

graph_pinned_result – Manages pinned results and pinned result collections in Optimizely Graph. See Pinned results﻿ in the Optimizely Graph documentation.

graph_synonyms – Manages synonyms in Optimizely Graph. Synonyms help you find content using alternative terms. See Synonyms﻿ in the Optimizely Graph documentation.

Property groups

cms_list_property_groups – Retrieve a list of all property groups available in CMS (SaaS). This tool returns raw JSON data.

cms_create_property_group – Create a property group used for content type properties in CMS (SaaS). Group names should be short, concise, and indicative of their use.

Taxonomy

cms_create_taxonomy_term – Creates a new category term in CMS (SaaS).

cms_delete_taxonomy_term – Deletes a category term by its hierarchical key.

cms_get_taxonomy_term – Gets the full details of a single category term by its hierarchical key.

cms_list_taxonomy_terms – Lists category terms in batches, returning root-level terms or the direct children of a parent.

cms_update_taxonomy_term – Updates the mutable fields of an existing category term.

cms_upload_media – Uploads an image, video, or document to the CMS (SaaS) media library from a URL or a file attached in Mark chat.

graph_content_type_schema – Use as your starting point for understanding the content structure within your Optimizely Graph instance. The tool lets you and Mark discover available content types and their fields, which is crucial for constructing accurate GraphQL queries.

graph_pinned_result – Manages pinned results and pinned result collections in Optimizely Graph. See Pinned results in the Optimizely Graph documentation.

graph_synonyms – Manages synonyms in Optimizely Graph. Synonyms help you find content using alternative terms. See Synonyms in the Optimizely Graph documentation.