System tools are built-in features that help Optimizely Opal 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 Opal, Optimizely Content Management System (CMS) (SaaS) includes a set of system tools to help you with CMS-related tasks, such as managing content.
Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts to calling the tool. If you do not provide a required parameter, Opal 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.
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.
-
When to use
- See all the content types that are available in your CMS (SaaS) instance.
- Understand the different kinds of content you can create or manage.
- Identify content types before performing actions like creating new content, getting detailed information about a specific content type (using
cms_get_content_type_details), or creating a new content type (usingcms_create_content_type). - Filter content types by their base type (for example, to see only pages or only components).
-
Properties
- (Optional)
BaseType– Filter the list of content types by their base type. If you do not provide aBaseType, the tool returns all content types. Valid values include the following:-
_page _experience-
_component -
_media -
_image -
_video -
_section
-
- (Optional)
-
Example prompts
- List all content types in my CMS (SaaS) instance.
- What content types are available?
- Show me all the page content types.
- Can you list all the component content types?
- What media content types do we have?
cms_get_content_type_details – Gets the full details of a content type, including properties, from CMS (SaaS).
-
When to use
- Inspect the complete structure and configuration of an existing content type.
- Understand all the fields (properties) defined for a content type, their types, and other settings.
- Get detailed information about a content type after listing them with the
cms_list_content_typestool. - Review a content type's definition before making updates with
cms_update_content_typeor creating new content based on it.
-
Parameters
-
ContentTypeKey– The unique machine-readable key for an existing content type in your CMS (SaaS) instance.
-
-
Example prompts
- Get the full details for the 'Article' content type.
- Show me all the properties of the content type with the key 'ProductPage'.
- Can you provide the complete schema for the 'HeroComponent' content type?
cms_create_content_type – Creates a new content type in CMS (SaaS).
- New content types must follow the same conventions (for example, naming conventions) as existing content types. Use the
cms_list_content_typestool to get existing content types and thecms_get_content_type_detailstool 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
groupfield for a property must reference an existing property group. Use thecms_list_property_groupstool to list existing property groups or thecms_create_property_grouptool 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 (e.g., 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_componentthat 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 owndisplayName,type,localizedstatus,requiredstatus,group,sortOrder, andindexingType. 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_componentbase 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_pageand_experiencebase 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.
cms_delete_content_type – Performs a non-disruptive deletion of a content type in CMS (SaaS).
- This tool is designed for safe deletion. If the content type is currently in use (meaning there are content instances based on it or other content types refer to it), the deletion fails to prevent data loss or broken references.
- If you need to delete a content type that is in use, you need to delete or reassign all content instances and references before attempting to delete the content type itself.
-
When to use
- Remove a content type that you previously created, for example, using the
cms_create_content_typetool. - Clean up unused or outdated content type definitions from your CMS (SaaS) instance.
- Ensure that a content type is no longer available for content creation, provided it's not in use.
- Remove a content type that you previously created, for example, using the
-
Parameters
-
ContentTypeKey– The unique machine-readable key of the existing content type in CMS (SaaS) instance that you want to delete.
-
-
Example prompts
- Delete the content type with the key 'OldBlogPost'.
- Remove the 'TemporaryPromo' content type from my CMS (SaaS.
- Can you delete the content type named 'DraftArticle'?
cms_update_content_type – Updates an existing content type in CMS (SaaS) using a JSON Merge Patch algorithm.
-
Non-disruptive updates – The
cms_update_content_typetool prioritizes the integrity of your existing content. If an update would cause aBreakingChangeserror (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
groupyou specify for a property must reference an existing property group. You can use thecms_list_property_groupstool to see available groups orcms_create_property_grouptool 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
displayNameof a field, update itsdescription, or adjust itsmaxLength). - Add new properties to an existing content type.
- Update the
baseType,CompositionBehaviors,Description,DisplayName, orMayContainTypesof a content type, provided the changes are non-disruptive.
- Modify specific properties of an existing content type (for example, change the
-
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
Tools labeled Preview are not available in Opal Chat by default and are in beta. Contact your Customer Success Manager to add your instance to the beta and then Opal administrators can go to the Tools tab and enable them in Opal Chat.
cms_create_content_item – Creates a new empty content instance in CMS (SaaS) based on an existing content type.
-
When to use
- When you need to create a new content item in the CMS.
- To create an empty draft content item before populating its properties.
- To create pages or experiences under other page or experience containers.
- To create shared or standalone components within a folder container.
-
Parameters
-
Locale– The locale or language code for this content instance. For example, 'en' or 'en-US'. -
ContentType– The key of the existing content type to create an instance of. -
DisplayName– The display name of the content instance. - (Optional)
Container– The key of the parent content item to create the item in. - (Optional)
Owner– The key of the owner content. - (Optional)
RouteSegment– URL segment for routing to this content (for pages and experiences).
-
-
Example prompts
- Create a new 'Article' content item named 'My First Article' in English.
- I want to create a new page called 'About Us' with the content type 'StandardPage' for the 'en-US' locale.
- Make a new component of type 'HeroBlock' named 'Homepage Hero' in the shared asset folder.
cms_get_content_data – Retrieves CMS (SaaS) content data for a specific content item.
-
When to use
- To retrieve the content and metadata of a specific content item.
- To verify the existence and details of a content item before performing other operations like deletion or update.
- To get the published version of a content item by default.
- To retrieve a specific version of a content item if a version number is provided.
-
Parameters
-
ContentKey– The unique identifier for the content item to retrieve. - (Optional)
ContentVersion– The specific version number of the content to retrieve.
-
-
Example prompts
- Get the content data for content item 'c3558e08-00a6-45d0-bfff-5bd2bda3acb5'.
- Show me the details of the article with key 'abc123def456'.
- Retrieve version 3 of the content item 'c3558e08-00a6-45d0-bfff-5bd2bda3acb5'.
cms_delete_content_item – Deletes a content item from CMS (SaaS) using its unique content key.
-
When to use
- When you need to remove a specific content item from CMS (SaaS).
- After verifying the content key using
cms_get_content_datato ensure the correct item is targeted for deletion. - When a content item is no longer needed or is outdated.
-
Parameters
-
ContentKey– The unique identifier for the content item to delete.
-
-
Example prompts
- Delete the content item with key 'c3558e08-00a6-45d0-bfff-5bd2bda3acb5'.
- Remove the old blog post.
- I want to delete content item 'abc123def456'.
cms_publish_content_item – Publishes a specific content version in CMS (SaaS), making it visible to site visitors.
-
When to use
- To make a specific version of a content item live and visible to site visitors.
- To immediately publish content or schedule it for a future date and time.
- When a content item has been reviewed and is ready for public release.
-
Parameters
-
ContentKey– The key of the content item to publish. -
ContentVersion– The version number of the content to publish. - (Optional)
DelayPublishUntil– Optional scheduled publish date and time in ISO 8601 format.
-
-
Example prompts
- Publish content item 'abc123def456' version 5.
- Schedule content 'c3558e08-00a6-45d0-bfff-5bd2bda3acb5' version 2 to publish on 2026-02-01 at 10 AM UTC.
- Make version 7 of the 'Homepage' content item live now.
cms_update_content_item – Updates the value for any property of a content item using a "JSON Merge Patch" algorithm.
-
When to use
- To modify existing properties of a content item.
- To create a new draft version or update an existing draft.
- To update specific fields without affecting other properties.
- To clear or remove property values. For example, setting an array to
[]or a property tonull. - To update complex properties like content references, link URLs, content areas, or rich text.
-
Parameters
-
ContentKey– The unique identifier for the content instance in CMS (SaaS). -
Properties– A JSON object containing the property names and their new values. - (Optional)
ContentVersion– The specific version number to update. - (Optional)
Locale– The locale and language code for the content item.
-
-
Example prompts
- Update the title of content item 'abc123def456' to 'New Product Launch'.
- Change the description of content 'c3558e08-00a6-45d0-bfff-5bd2bda3acb5' in English to 'An exciting new feature'.
- Set the 'HeroImage' of content 'xyz789' to 'cms://content/image_guid'.
- Clear the 'Tags' list for content item 'tag_item_key'.
Get content
cms_get_content_data – Get the data from a specific content instance in CMS (SaaS).
-
When to use
- Retrieve the content of a specific item from your CMS (SaaS) instance.
- Access a particular version of a content item, for example, to compare changes or revert to an older state.
- Get the published version of a content item to display or analyze.
-
Parameters
-
ContentKey– The key of the content item you want to retrieve. This is the unique identifier for the content instance in CMS (SaaS), typically formatted as a GUID (with or without hyphens). For example,c3558e08-00a6-45d0-bfff-5bd2bda3acb5orc3558e0800a645d0bfff5bd2bda3acb5. - (Optional)
ContentVersion– The specific version number of the content key you want to retrieve. You should include this parameter only when you explicitly provide a version number. Otherwise, omit it to get the published versions.
-
-
Example prompts
-
Get the content data for the article with key
c3558e08-00a6-45d0-bfff-5bd2bda3acb5. - Show me the content of the 'Homepage' page.
-
Retrieve version 3 of the content with key
12345678-1234-1234-1234-1234567890ab. - What is the published content for the 'AboutUsPage'?
-
Get the content data for the article with key
Idea Lab tools
get_idealab_domain_competition – Returns Idea Lab domain organic competition data.
-
When to use
- Analyze the organic search competition for a particular website.
- Understand the competitive landscape for a domain in specific geographic regions.
- Identify key competitors and their performance in search engine rankings.
-
Parameters
-
domain– The domain for which you want to analyze the competition. -
country_code– The two-letter ISO country code (for example, 'us', 'gb', or 'se') for the SEO analysis.
-
-
Example prompts
- Analyze the organic competition for example.com in the US.
- What is the domain competition for mywebsite.com in the UK?
- Show me the SEO competition for optimizely.com in Sweden.
get_idealab_domain_keywords – Returns Idea Lab domain organic competition data.
-
When to use
- Identify the keywords a particular domain ranks for in organic search results.
- Analyze a website's keyword portfolio in a specific country.
- Filter keywords to include or exclude certain terms (for example, branded keywords or specific topics).
- Sort keywords based on various metrics like traffic, position, or search volume.
-
Parameters
-
domain– The domain for which you want to analyze keywords. -
country_code– The two-letter ISO country code (for example, 'us', 'gb', or 'de') for the keyword analysis. - (Optional)
include_keywords– A comma-separated list of keywords that must be present in the results. - (Optional
exclude_keywords– A comma-separated list of keywords that must not appear in the results. - (Optional)
sort_by– A comma-separated list of fields to sort the results by. Use a '-' prefix for descending order (for example,sort_by='traffic,-position').
-
-
Example prompts
- What keywords does example.com rank for in the US?
- Show me the top keywords for mywebsite.com in the UK, excluding 'brand name'.
- List keywords for optimizely.com in Sweden, including 'experimentation' and sorting by traffic descending.
-
Get all keywords for
digitalmarketing.comin Germany that contain 'SEO' or 'content'.
get_idealab_keyword_infos – Returns Idea Lab SEO keyword information.
-
When to use
- Get in-depth SEO insights for a particular keyword.
- Understand the performance and characteristics of a keyword in a specific geographic market.
- Research keywords for content planning, SEO strategy, or paid advertising campaigns.
-
Parameters
-
keyword– The specific keyword for which you want to retrieve information. -
country_code– The two-letter ISO country code (for example,, 'us', 'gb', or 'au') for the SEO analysis.
-
-
Example prompts
- What are the keyword infos for "A/B testing" in the US?
- Show me the SEO data for "content marketing strategy" in the UK.
- Get the keyword information for "experimentation platform" in Australia.
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.
-
When to use
- Identify common questions users ask related to a particular keyword.
- Generate ideas for content, blog posts, or FAQ sections.
- Understand the information gaps or specific queries users have about a topic.
- Improve your SEO strategy by addressing user questions directly.
-
Parameters
-
keyword– The specific keyword for which you want to find related questions. -
country_code– The two-letter ISO country code (for example,, 'us', 'gb', or 'ca') for the analysis.
-
-
Example prompts
- What questions are associated with "conversion rate optimization" in the US?
- Find keyword questions for "headless CMS" in GB.
- Show me common questions about "A/B testing tools" in ca.
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.
-
When to use
- Discover new keyword ideas for SEO and content strategies.
- Expand your understanding of a topic by identifying related search terms.
- Find long-tail keywords or variations that users might search for.
- Improve your content's relevance and coverage by incorporating related terms.
-
Parameters
-
keyword– The main keyword for which you want to find related terms. -
country_code– The two-letter ISO country code (for example., 'us', 'de', and 'au') for the analysis.
-
-
Example prompts
- What are the related keywords for "digital marketing" in the US?
- Show me keywords related to "e-commerce platforms" in DE.
- Find related search terms for "customer experience" in AU.
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 Opal discover available content types and their fields, which is crucial for constructing accurate GraphQL queries.
-
When to use
- To explore available content – If you want to know what types of content (for example, articles, products, pages) are stored in your Optimizely Graph instance.
- To understand content structure – If you need to see the fields and properties associated with a specific content type before querying it.
-
To build GraphQL queries – If you need the exact content type names and field names for use with the
graph_content_graphql_executortool.
-
Parameters
- (Optional)
searchPhrase– A text string to filter content types that are relevant to your question, for example, "news article" or "product details". If left empty, all content types are returned. - (Optional)
itemMinimumScore– The minimum score for items to be considered relevant based on the search phrase. - (Optional)
contentTypeFacetLimit– The maximum number of content types to return from the facet.
- (Optional)
-
Example prompts
- What content types are available in Optimizely Graph?
- Show me the schema for content types related to 'blog posts'.
- I want to see all content types and their fields that are relevant to 'products'.
- Can you list content types that might contain information about 'customer reviews'?
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).
-
When to use
- To retrieve specific content items – If you need to fetch detailed data for articles, products, pages, or any other content type.
- To filter content based on criteria – If you want to find content that matches certain conditions, for example, articles published within a date range or products with a specific tag.
- To sort content results – If you need to order content by fields like publication date, title, or price.
-
To paginate through large datasets – If you need to retrieve content in chunks using
skipandlimit. - To get aggregated data (facets) – If you want to count occurrences of values within a field, for example, the number of articles per author or products per category.
-
Parameters
-
query– The GraphQL query to execute. - (Optional)
variablesAsJson– A JSON string representing variables for the GraphQL query.
-
-
Example prompts
- Get the titles and descriptions of all 'NewsArticle' content types.
- Find all 'Product' content types where the 'price' is greater than 50 and less than 100, and order them by price in ascending order. Also, show me the 'name' and 'sku' of these products.
- Count how many 'BlogPosts' were published each month in 2024, and list their titles.
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.
-
When to use
- For simple keyword searches – If you need to find content items that contain a specific phrase or keyword.
- When you know the content type – If you are looking for content within a known content type, for example, Search for 'summer sale' in 'Promotions'.
-
As a quick lookup – If the
graph_content_graphql_executortool seems too complex or overextravagant for your immediate need.
-
Parameters:
-
searchPhrase– The search phrase to use when searching for content. - (Optional)
contentTypeName– The specific content type to search within, for example, "Article" or "Product". If not provided, it defaults to "Data" (which might search across various types depending on configuration). -
(Optional)
outputFieldsAsGraphQLOutput– The specific fields you want to retrieve for the matching content items, in GraphQL output format. If not provided, it defaults to_fulltext. For example, the following:"id name createdBy { id name }"
-
-
Example prompts
- Search for 'holiday promotions' in the 'Campaign' content type.
- Find any 'Article' content that mentions 'customer experience' and return their titles and URLs.
- What 'Product' content contains the phrase 'new features'?
- Show me all content related to 'Optimizely DXP'.
Property groups
Property groups are used to organize properties within content types, making the content editing interface more structured.
cms_list_property_groups – Retrieve a list of all property groups available in CMS (SaaS). This tool returns raw JSON data.
-
When to use
- See all existing property groups in your instance of CMS (SaaS).
- Identify available groups to use when creating or updating content types with the
cms_create_content_typetool orcms_update_content_typetool. - Determine if a new property group needs to be created before defining new content type properties.
-
Parameters
-
IncludeSystemGroups– Indicates whether pre-built property groups from the 'system' source should be included in the results.
-
-
Example prompts
- List all property groups in my CMS (SaaS) instance.
- Show me the available property groups.
- Are there any property groups for 'SEO'?
- Include system groups when listing property groups.
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.
cms_list_property_groups tool to check for existing property groups before creating a new one to avoid duplication.-
When to use
- Create a new category or section for properties within your content types.
- Improve the organization and usability of the content editing experience.
- Ensure that related properties are logically grouped together.
-
Parameters
-
DisplayName– The human-readable name of the property group (for example, 'SEO Settings'). -
Key– A machine-readable key that must be unique in CMS (SaaS) (for example, 'SEO_Settings').
-
-
Example prompts
- Create a property group called 'SEO Settings' with the key 'SEO_Settings'.
- I need a new property group for 'Product Details'.
- Make a group for 'Author Information'.
Search engine optimization (SEO)
cms_seo_analysis – Analyze CMS (SaaS) content for SEO performance, and get AI-powered recommendations for optimization. This tool focuses on providing insights and suggestions without directly modifying your content.
-
When to use
- Get a detailed SEO analysis of a specific content item.
- Understand the current SEO state of your content.
- Receive AI-generated recommendations for improving your content's search engine visibility and ranking.
- Identify opportunities to optimize meta titles, descriptions, keywords, and other SEO-related elements.
-
Parameters
-
ContentKey– The GUID of the content item (with or without hyphens) that you want to analyze for SEO. -
PreviewUrl– The preview URL of the content. This is essential for the tool to fetch and analyze the rendered HTML content. - (Optional)
AiAnalysisResult– The AI-generated SEO analysis result from a previous analysis prompt. This can be used to provide context for further analysis. - (Optional)
Question– An optional question or specific focus area for the SEO analysis. For example, you might ask "How can I improve the meta description?"
-
-
Example prompts
-
Perform an SEO analysis on the content with key
c3558e08-00a6-45d0-bfff-5bd2bda3acb5using the preview URLhttps://example.com/preview/my-blog-post. - Analyze the SEO of my latest product page and give me recommendations.
-
What are the SEO opportunities for the content at
https://mywebsite.com/preview/landing-page? -
I want an SEO analysis for content GUID
12345678-1234-1234-1234-1234567890abfocusing on improving its keyword density.
-
Perform an SEO analysis on the content with key
cms_seo_edit – Edit and apply SEO recommendations to CMS (SaaS) content. This tool provides an interactive form for editing SEO fields, including meta titles, descriptions, and social media tags. Use this tool after running the cms_seo_analysis tool to apply the recommended changes.
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.
Article is closed for comments.