System tools overview

  • Updated

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.

This page lists all built-in system tools provided and maintained by Optimizely so you can see what actions are available for your workflows. 

Additionally, Optimizely maintains tools for specific Optimizely products. See the following documentation for product-specific tools:

You can ask Opal 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 Opal Chat.

System tools by functionality

Click on a tool's name to expand it and learn more about when to use the tool, required and optional parameters, and example prompts on how to call the tool. If you do not provide a required parameter, Opal prompts you for it.

Audio and video

audio_video_processing – Process audio and video files for transcription, subtitle generation, summarization, and content analysis.
  • When to use
    • Extract speech as plain text transcription from uploaded audio or video files.
    • Generate .srt subtitle files with accurate timestamps from media.
    • Summarize the main points of an audio recording or video.
    • Answer specific questions about the content of a media file.
  • Parameters
    • action – What to do with the media file. Options include the following: 
      • transcribe' – Extract speech as plain text transcription.
      • srt – Extract speech with timestamps in SRT subtitle format.
      • summarize – Provide a summary of the content.
      • analyze – Answer a specific question about the media content.
    • file_id – The file ID as a plain GUID or UUID string. For example, 1c60cd99-430b-489e-9d94-6de725bff0d8. Do not pass a full file object, URL, or GCS path. Only pass the unique identifier.
    • (Optional) language – Target language for transcription or subtitles. For example, English, Spanish, or French. If not specified, auto-detects the spoken language.
    • (Optional) query – Additional instructions or question about the media. Required when action is analyze, optional for other actions to refine output.
  • Example prompts
    • Please transcribe this audio file, for example, using the action transcribe and the file ID.
    • Can you summarize the video I just uploaded, for example, to get a quick overview of the meeting?
    • Analyze the recording to answer my question, for example, "What were the next steps mentioned?"

Agents

execute_specialized_agent – Execute a specialized agent with structured parameters.
  • When to use
    • Run an agent that requires specific, structured JSON inputs or parameters.
    • Execute an agent after verifying its existence and exact parameter schema using the search_agents tool.
    • Pass precise values like names, dates, or file URLs into an agent's defined inputs.
  • Parameters
    • agent_id – The ID of the specialized agent to execute
    • parameters – JSON string of parameters to pass to the specialized agent
  • Example prompts
    • Execute the specialized agent with ID agent-123, for example, using the provided JSON parameters.
    • Can you run the campaign agent, for example, passing my target audience and budget in the parameters?
    • I want to execute the specialized agent, for example, with the structured input for age and location.
execute_workflow_agent – Execute a workflow agent with plain text input.
  • When to use
    • Run an agent that processes natural language commands instead of structured JSON.
    • Trigger complex, multi-step workflows based on a clear, descriptive text input.
    • Execute an agent to accomplish a goal described conversationally.
  • Parameters
    • agent_id – The ID of the workflow agent to execute
    • input_text – Plain text input for the workflow execution
  • Example prompts
    • Execute the workflow agent campaign-workflow, for example, with the input text "Create a marketing campaign for Nike shoes".
    • Run the content workflow agent, for example, and tell it to "Draft a blog post about AI trends".
    • Can you execute the data analysis workflow, for example, to "Analyze the Q3 sales data"?
search_agents – Search for agents by query (agent_id, name, description, keywords, or use case).
  • When to use
    • Find available specialized or workflow agents based on a keyword, name, or use case.
    • Retrieve the required parameter schema for a specialized agent before attempting to execute it.
    • List all available agents by providing an empty search query.
  • Parameters
    • (Optional) search_query – Search query to find agents, it can be the ID of the agent, name of the agent, or a description.
  • Example prompts
    • Search for agents related to email, for example, using the query "email".
    • Find the exact ID and parameter schema for the campaign agent, for example, searching for "campaign creation".
    • Can you list all available agents, for example, by running a search with an empty query?

Browse the web

browse_web – Opens and extracts content from multiple webpages concurrently and returns the content in Markdown or HTML format.
  • When to use
    • When you need to gather information from one or more specific URLs.
    • When you want to summarize the content of a webpage.
    • When you need to extract raw HTML content from a URL.
    • When you are provided with a list of URLs and need to process them.
  • Parameters
    • urls – A list of URL items. Each item is an object that must contain a url and can optionally contain information_needed to specify what information to extract from that particular URL, and output_format (either 'markdown' or 'raw') to specify the desired output format for that URL.
    • default_information_needed – A string representing the default query to use if information_needed is not specified for a particular URL. This parameter is required when the default_output_format is 'markdown'.
    • default_output_format – A string specifying the default output format ('markdown' or 'raw') if not specified per URL. 'raw' formats return content without LLM processing.
  • Example prompts
    • Please summarize the main points of the article at https://www.optimizely.com/insights/blog/ and also get the raw content from https://www.example.com.
    • Can you tell me what is on this page: https://www.optimizely.com/products/experiment/web/.
    • Browse these two links for me: https://www.example.org and https://www.another-example.net.
browse_web_html – Browses a single webpage, extracts information, and returns content in raw HTML format.
  • When to use
    • When you need the complete, unprocessed HTML source code of a specific webpage.
    • When you want to analyze the structure or elements of a page directly.
    • When you are not looking for a summary but the full content as rendered by a browser.
  • Parameters
    • url – The URL of the webpage to browse and return raw content from.
  • Example prompts
    • Get the raw HTML from https://www.optimizely.com.
    • I need the full content of this page: https://www.example.com/product-details.
    • Can you fetch the HTML source of https://support.optimizely.com/hc/en-us/articles/36354416686477-Optimizely-Opal-overview.
take_webpage_screenshot – Captures a screenshot of a webpage by given URL.
  • When to use
    • When you need a visual representation or preview of a webpage.
    • When you want to see how a specific URL (including images or PDFs) appears in a browser.
    • To get a visual overview of content without needing to browse it yourself.
  • Parameters
    • url – The URL of the webpage to take a screenshot of.
  • Example prompts
    • Take a screenshot of https://www.optimizely.com.
    • Can you show me what https://www.example.com looks like?
    • Get a preview of the page at https://www.optimizely.com/blog/latest-posts/.

Canvas

Your active canvas provides a dynamic and collaborative environment where you and Optimizely Opal can build, customize, and deliver interactive digital assets, applications, and complex content. This workspace lets you create and manage digital assets in real-time. 

See Canvas overview for more information.

create_csv_canvas – Create a  Comma-Separated Values (CSV) canvas from CSV file URL or direct CSV content. Stores as raw CSV string with text/csv MIME type.
  • When to use
    • Generate a new, interactive CSV table from raw text content inside the canvas.
    • Load and display an external CSV file using its URL for real-time viewing and editing.
    • Initialize a data workspace to analyze and manipulate tabular data.
  • Parameters
    • title – Title or name for the CSV canvas
    • (Optional) content – Raw CSV content as string to display directly (mutually exclusive with csv_url).
    • (Optional) csv_url – URL to the CSV file to download and display (mutually exclusive with content).
    • (Optional) space_description – Description for the workspace if creating new
    • (Optional) workspace_id – Override the contextual workspace ID. Is ignored if the tool is not called inside a specialized agent test run.
    • (Optional) workspace_name – Name for the workspace if creating new (defaults to the canvas title).
  • Example prompts
    • Create a new CSV canvas titled "Q1 Sales Data", for example, using the raw CSV content I pasted above.
    • Please load this CSV file into a canvas, for example, using the URL https://example.com/data.csv and naming it "User Metrics".
    • I need a new data table, for example, create a CSV canvas called "Inventory" with this text content.
edit_canvas – Edits existing AI canvas (element) content using JSON Patch operations.
  • When to use
    • Modify specific parts of an existing canvas, whether it is a Markdown document, HTML code, or a React or Next.js application.
    • Programmatically update content in a canvas, for example, changing a title, updating a section of text, or replacing a code block.
    • Make iterative changes to a canvas's content based on feedback or new requirements.
  • Parameters
    • element_id – The unique identifier of the canvas (element) you want to modify.
    • base_commit_id – A crucial identifier representing the current version of the canvas. It is used to prevent conflicts if multiple people (or the AI) are trying to edit the same canvas simultaneously. When you are editing a canvas in the UI, this ID is typically provided by the system.
    • patch_operations – This is a list of instructions (list of dictionaries), in JSON Patch format, that describe the changes you want to make to the canvas content. These operations can include adding, removing, or replacing content, or applying a text-based diff patch.
  • Example prompts
    • Since this tool operates at a technical level with JSON Patch operations, direct user prompts to execute it are less common. Instead, you would typically ask the AI to make a change, and the AI would then use edit_canvas to perform that change. The following are examples of user requests that would likely trigger the AI to use this tool:
    • Can you update the main heading in my "Marketing Plan" canvas to "Q4 Marketing Strategy"?
    • In my "Product Page" React component, replace the old image URL with https://new-image.com/product.jpg.
    • Please remove the third bullet point from the "Key Features" section in my markdown document.
    • I want to replace the entire content of my "About Us" page canvas with this new HTML code.
edit_csv_canvas – Edit a CSV canvas with operations append_rows, replace_content, update_rows, delete_rows, and reorder_columns.
  • When to use
    • Append new records to an existing CSV canvas using JSON formatted rows.
    • Update specific cells or delete specific rows in the CSV table based on their index.
    • Reorder columns or entirely replace the content of a CSV canvas.
  • Parameters
    • base_commit_id – Current commit ID for optimistic locking (safeguard that prevents multiple people or Opal from accidentally overwriting each other's work when editing the same document at the same time).
    • element_id – ID of the CSV canvas to edit.
    • operation – Operation to perform on the CSV canvas.
    • (Optional) column_names – Column names to keep and their order (for reorder_columns operation).
    • (Optional) new_csv_content – Complete CSV content string to replace existing content (for replace_content operation).
    • (Optional) row_indices – List of zero-based row indices to update or delete (for update_rows and delete_rows operations).
    • (Optional) rows_json – JSON string containing array of rows. 
      • For append_rows – [['val1', 'val2'], ['val3', 'val4']]. 
      • For update_rows – [['new_val1', 'new_val2']] (must match length of row_indices).
    • (Optional) workspace_id – Override the contextual workspace ID. Is ignored if the tool is not called inside a specialized agent test run.
  • Example prompts
    • Add these two new rows to the current CSV canvas, for example, using the append_rows operation.
    • Delete the third row from the table, for example, setting the operation to delete_rows and using row index 2.
    • Rearrange the columns so that "Email" comes before "Name", for example, using the reorder_columns operation.
canvas_to_file – Export canvas content to a file. Converts canvas data to appropriate file format based on canvas MIME type.
  • When to use
    • Export the final version of a canvas document to a standard file for downloading or sharing.
    • Convert a markdown or HTML canvas into a PDF document by specifying a .pdf filename.
    • Save interactive canvas content (like CSV or code) into a physical file within the workspace.
  • Parameters
    • canvas_id – ID of the canvas to export to file.
    • (Optional) content_type – MIME type override (uses canvas MIME type if not provided).
    • (Optional) filename – Desired filename with extension (auto-generated if not provided).
    • (Optional) workspace_id – Workspace ID (auto-detected if not provided).
  • Example prompts
    • Export this canvas to a file, for example, naming it "report.pdf" to automatically convert the markdown to a PDF.
    • Save our code canvas as a file, for example, with the filename "app.js".
    • Can you convert the current data canvas to a downloadable file, for example, using the ID of the CSV canvas?
create_canvas – Creates an interactive AI canvas (element) where you and Opal can collaboratively edit content in real-time. Canvases are versatile and can hold various types of content, from documentation to code.
  • When to use
    • Create any new editable content, including documents, files, presentations, code, or reports.
    • Collaborate on content.
    • Generate interactive (runnable) code. 
  • Parameters
    • name – The name of the canvas (element) to create.
    • content – The initial content you want to place in the canvas (element).
    • mime_type – The MIME type of the element content which determines how i i's rendered and interpreted. Valid options include the following:
      • text/markdown – For documentation, notes, and articles.
      •  text/html – For pure HTML content.
      • application/x-reactjs – For React components and applications.
      •  application/x-nextjs – For Next.js pages and applications.
    • (Optional) space_name – The name for the workspace (space) if you are creating a new one. If you do not provide one, it defaults to the canvas (element) name.
    • (Optional) space_description – A description for the workspace (space) if you are creating a new one.
  • Example prompts
    • Create a new markdown document for my marketing brief.
    • Write a React component for a hero section.
    • Make an HTML page with a simple contact form.
    • Can you create a Next.js application for a product listing page?
    • I need a canvas to draft a new blog post.
get_canvas – Retrieves an AI canvas (element) with current content and metadata for read-only operations.

  • When to use

    • Show the current content of a canvas to yourself or others.
    • Read the content of a canvas for processing or understanding, such as reviewing a document or code.
    • Verify if a canvas exists and retrieve its metadata.
    • Any task where you need to see the content but do not intend to modify it.
    Do not use this tool to get the base_commit_id before applying patches with edit_canvas. Th base_commit_id for editing must come from the UI's current element state to ensure you are working with the most up-to-date version and avoid conflicts.
  • Parameters
    • element_id – The ID of the canvas (element) you want to retrieve.
  • Example prompts
    • Show me the content of my "Project Proposal" document.
    • What is in the canvas named "Homepage Redesign"?
    • Can you display the code for the "User Authentication" React component?
    • Retrieve the details of ELEMENT_ID.
get_canvas_by_workspace – Lists all canvases (elements) in the current thread's workspace. It provides a summary of each element, including its ID, name, and type, but not its full content.
  • When to use
    • See all the content you have created or have access to in the current space.
    •  Identify specific canvases before performing actions like retrieving their full content (get_element) or editing them (edit_canvas).
    • Check what content already exists. Before creating a new canvas, you might want to see if a similar one already exists.
  • Parameters
    • None
  • Example prompts
    • List all the canvases in this space.
    • What content do I have in my current workspace?
    • Show me all the elements I've created.
    • Can you give me a summary of all the canvases here?
get_canvas_workspace – Returns details about the current workspace, including its metadata and current version information.
  • When to use
    • Check general information about your current workspace.
    • Retrieve metadata associated with the space.
    • Verify that a space exists for your current thread.
  • Parameters
    • None
  • Example prompts
    • What is this workspace about?
    • Can you tell me about the current space?
    • Show me the details of this project space.
create_powerpoint_canvas – Imports an external PowerPoint file (.pptx) and sets it up as a canvas for viewing, review, and text-based editing. The tool extracts slide text and prepares the file for PDFTron rendering.
  • When to use
    • Use this tool when you want to load an existing .pptx file into an interactive canvas for editing, reviewing, or rewriting slide content.
  • Parameters
    • name –  The name of the canvas (element) to create.
    • ppt_url – Specifies the URL of the .pptx file to import.
  • Example prompts
    • Import this PowerPoint into a new canvas: <URL>.
    • Create a canvas from this .pptx so I can rewrite the content.
update_powerpoint_canvas – Updates an existing PowerPoint canvas by modifying the underlying .pptx file. It supports deleting slides, replacing text, copying slides, and inserting images into placeholders.
  • When to use
    • Use this tool when you want to edit PowerPoint content already imported into a canvas.
  • Parameters
    • operation – Indicates the type of PowerPoint update to perform.
    • slide_numbers – Lists slides to delete (delete_slide operation).
    • search_text – Specifies text to find during replacement.
    • replace_text – Specifies text to insert during replacement.
    • source_ppt_url – Identifies the external PowerPoint used for copying slides.
    • source_slide_number – Selects which slide to copy from the source file.
    • image_url – Provides the image to insert into a placeholder.
    • slide_number – Selects the slide for image placement or matching.
    • placeholder_text_regex – Matches the target placeholder to replace with an image.
  • Example prompts
    • Delete slides 2 and 4 from this presentation.
    • Replace all instances of ‘Q3 2024’ with ‘Q4 2024’.
    • Copy slide 1 from this external PowerPoint into this canvas.
    • Insert this logo into the placeholder labeled ‘Logo’ on slide 3.
workspace_list_files – List all files in a workspace directory (recursive).
  • When to use
    • Discover all available instruction files and attachments you uploaded.
    • Explore the directory structure of the sandboxed workspace.
    • Locate output files generated by previous code executions.
  • Parameters
    • (Optional) path – Directory path to list. Must be under /workspace/input/, /workspace/output/, or /context/.
  • Example prompts
    • List all the files in my workspace, for example, checking the input directory for my uploaded images.
    • Can you show me what files are available in the output directory, for example, after running the data analysis script?
    • I need to find the exact file paths in the context folder, for example, to read my personal files.
workspace_read_file – Read the contents of a file from the workspace, with support for chunking large files and auto-converting Microsoft Office documents.
  • When to use
    • Extract text or data from uploaded attachments like JSON, CSV, or text files.
    • Read output files produced by previous code executions to present to the user.
    • Access and read large files incrementally by chunking.
  • Parameters
    • path – Full path to the file to read. Must be under /workspace/input/, /workspace/output/, or /context/. Example: /workspace/input/instructions/guid/brand_guide.pdf.
    • (Optional) chunk_index – Zero-based chunk index for large files. If the file is large, it is split into chunks.
  • Example prompts
    • Read the contents of the uploaded guide, for example, the file at /workspace/input/brand_guide.pdf.
    • Please fetch the output JSON file, for example, to check the results of the script.
    • Can you read the next chunk of the large dataset, for example, using chunk index 1?
workspace_search – Search for files in the workspace by filename or content.
  • When to use
    • Find a specific file when the exact path is unknown.
    • Search for specific keywords or content across all text files in the workspace.
    • Quickly locate configuration files, notes, or code scripts within the input or output directories.
  • Parameters
    • query – Search query, matches against filenames and file contents.
    • (Optional) max_results – Maximum number of results to return.
  • Example prompts
    • Search the workspace for any files containing the keyword "revenue", for example, to find the monthly report.
    • Find the Python script we were working on earlier, for example, by searching for "data_analysis".
    • Can you locate the config file, for example, searching the workspace for "settings.json"?

Code execution

code_execute – Execute code in a sandboxed environment supporting Python, Bash, and Node.js.
  • When to use
    • Analyze data, run calculations, or generate charts using Python.
    • Process uploaded files such as CSV, Excel, images, or PDFs.
    • Run dev tools, shell commands, or automate workflows using Bash.
    • Generate PowerPoint or Word documents using Node.js or Python.
  • Parameters
    • code – Source code to execute. Read uploaded files from /workspace/input/. Write outputs to /workspace/output/.
    • (Optional) language – Programming language. Option include the following:
      • python for data science, document processing, and visualization. 
      • bash for shell commands, git operations, build automation, and dev tooling. 
      • node for JavaScript execution, PowerPoint and Word document generation.
  • Example prompts
    • Please execute a Python script to analyze the uploaded sales data, for example, creating a revenue chart.
    • Run a bash command to unzip the provided archive, for example, unzip /workspace/input/assets.zip -d /workspace/output/.
    • Use Node.js to generate a PowerPoint presentation, for example, reading the markdown file and outputting a slide deck.

Date

get_today – Returns the current UTC date and time in a human-readable Markdown format.
  • When to use
    • When you need to know the current date and time in UTC.
    • When a task or request requires a timestamp or a reference to the current day.
  • Parameters
    • This tool has no parameters.
  • Example prompts
    • What is today's date?
    • Can you tell me the current UTC time?
    • What is the date and time right now?

Email notifications

send_email – Composes and sends emails as a notification tool. Supports setting email triggers by specifying various parameters. See Email domain configuration.
  • Use for notifications – Send status updates and alerts only. Do not send email marketing campaigns. Use a dedicated email marketing platform instead.
  • Limit to internal recipients – Send emails to your employees or approved team mailboxes only. Do not send emails to customers or external audiences.
  • When to use
    • When you need to send an email to one or more recipients.
    • When the email needs to include a subject and a body.
    • When you want to include attachments from the Opal backend.
    • When you need to CC or BCC other recipients.
  • Parameters
    • recipient_emails – A comma-separated list of primary recipient email addresses.
    • subject – The email subject line.
    • body – The email body content (HTML or plain text, auto-detected).
    • (Optional) from_email – The sender email address. This can be left blank, and Opal uses a default sender.
    • cc_emails – A comma-separated list of CC recipient email addresses.
    • bcc_emails – A comma-separated list of BCC recipient email addresses.
    • attachments – A comma-separated list of Opal file IDs or file links for attachment.
  • Example prompts
    • Send an email to john.doe@example.com with the subject "Project Update" and the body "The project is on track."
    • Please email the marketing team at marketing@optimizely.com about the new campaign, and CC my manager at manager@optimizely.com.
    • I need to send a quick note to the sales team, subject "New Product Launch", body "See attached for details", and attach file_id_123 and file_id_456.

File operations

convert_to_pdf – Converts a file or webpage to PDF.
  • When to use
    • When you need to convert a document (identified by a file ID or URL) into a PDF.
    • When you want to save a webpage as a PDF.
  • Parameters
    • source – The file ID, file URL, or webpage URL to convert to PDF (string). This accepts UUID format file IDs, Opal Backend file links, or any webpage URL.
  • Example prompts
    • Convert the file with ID 'file_12345' to PDF.
    • Can you convert the webpage at https://www.optimizely.com/products/web-experimentation/ to a PDF?
    • I need a PDF version of this document: https://example.com/report.docx.
get_file_metadata – Retrieves metadata for a file, such as dimensions or alt text.
  • When to use
    • When you have a file ID (from a previous upload or generation) and need to access its associated metadata.
    • When you want to confirm details about a file, such as its name, type, or size.
  • Parameters
    • file_id – The file ID from a previous upload in Opal.
  • Example prompts
    • What is the metadata for file ID 'file_abc123'?
    • Can you give me the details of the file with ID '40026099-7bf5-4e36-b5b5-86ffdf4f1de0'?
    • Retrieve information about the uploaded document, its ID is 'doc_xyz789'
read_file_content – Reads a file from the Opal backend with configurable encoding.
  • When to use
    • When you need to access the textual or binary content of a file that has been previously uploaded to or generated within the Opal Backend.
    • When you know the file_id of a file and want to retrieve its content for further processing or display.
  • Parameters
    • file_id – The file ID from the Opal Backend.
    • encoding – The file encoding to use, or 'binary' for binary files.
  • Example prompts
    • Read the content of file 'file_12345'.
    • Can you show me what is inside the document with ID 'doc_xyz789'?
    • Retrieve the binary content of the image file 'image_id_001'.
retrieve_file_from_gcs_uri – Read file content directly from a Google Cloud Storage (GCS) URI.
  • When to use
    • When you need to access the content of a file that is stored in GCS.
  • Parameters
    • gcs_uri – The GCS URI of the file.
    • (Optional) mime_type – The expected MIME type of the file. Should only be provided if you are certain of the MIME type.
  • Example prompts
    • Retrieve the content of the file located at gs://my-bucket/documents/report.pdf.
    • Can you get the data from this GCS URI: gs://data-lake/analytics/sales_data.csv?
    • Fetch the image from gs://product-images/new_product.png.
write_content_to_file – Saves generated content by Opal as a file in the backend. 
  • When to use
    • When you need to save any generated content (text, code, markdown) as a file.
    • To store temporary or permanent content that might be used by other tools (for example, as an attachment for an email).
  • Parameters
    • content – The content to write to the file.
    • filename – The desired filename with its extension (for example, "document.pdf" or "image.png").
    • (Optional) content_type – The MIME type of the content, auto-detected if not provided.
  • Example prompts
    • Save this markdown content as "my_report.md".
    • Write the following HTML code to a file named "index.html".
    • Create a text file called "meeting_notes.txt" with the content "Discussed Q4 strategy and next steps."

Ideate and reason

evaluate_response – Evaluates LLM responses as a quality assurance tool. Takes an original prompt and the LLM's response, then uses another LLM to provide a quality score (0-100) and feedback for improvement.
  • When to use
    • When you need to verify if your generated answer meets expected format and quality standards before finalizing your response.
    • To get objective feedback on an LLM's output against a given prompt and criteria.
  • Parameters
    • original_prompt – The original prompt or question that you asked the LLM.
    • llm_response – The LLM's response that needs to be evaluated for quality and format.
    • (Optional) evaluation_criteria – Specific criteria to focus on during evaluation.
  • Example prompts
    • Evaluate my response to the user's request for a campaign brief.
    • Check if this generated code adheres to the specified formatting guidelines.
    • Assess the quality of my explanation for the browse_web tool based on the original prompt.
ideate – Generates a plan and suggests available tools for complex or ambiguous tasks. Use this tool when Optimizely Opal is overwhelmed with how to proceed or needs a plan for how to address a given problem or topic.
  • When to use
    • When you are unsure how to proceed with a complex request or problem.
    • When you want a strategic plan or a step-by-step approach to address a query.
    • When you need to break down a large problem into smaller, manageable steps.
    • When you want to explore different ways to use the available tools to achieve a goal.
  • Parameters
    • what_to_ideate – The topic or problem to ideate on. This should be a clear description of what you want to brainstorm or plan for.
    • list_of_tools – A list of tools that can be suggested during the ideation process. This helps the ideation process focus on practical applications of the available functionalities.
  • Example prompts
    • Ideate on how to create a new marketing campaign using the available tools.
    • I need a plan to analyze website performance and suggest improvements.
    • How can I use the tools to generate customer segments and then create targeted content.
reasoning_step – Articulates internal intermediate reasoning steps, plans, or observations for complex questions to help Opal continue multi-step work. This is particularly useful for complex questions that require careful consideration or decomposition before formulating a final answer.
  • When to use
    • Whenever Opal needs to think through a complex problem or user request.
    • To break down a multi-step task into a clear plan.
    • To analyze the user's query and determine the best approach using available tools.
    • To record my internal observations or decisions before generating a response.
  • Parameters
    • thought_process – where Opal articulate its detailed internal reasoning, step-by-step plan, analysis of the query, or any scratchpad notes needed to arrive at the final answer.
  • Example prompts
    • I need to determine the best sequence of tool calls to fulfill this request.
    • Let me analyze your intent and identify any ambiguities.
    • My plan is to first search for relevant information, then synthesize it, and finally present it to the user.

Images

analyze_image_content – Helps Opal understand and interpret the visual content of images, whether they are screenshots you provide or images Opal has found through a search. Opal can answer your questions based on what it "sees" in the image.
  • When to use
    • Describe what is present in an image.
    • Identify objects, people, or scenes within a picture.
    • Answer specific questions about the visual information in an image.
    • Extract context or details from a screenshot or any other image.
  • Parameters
    • file_id – The ID of the image file you want me to analyze. This would typically be an ID you received from Opal after uploading an image or if Opal generated an image for you.
    • query – The question or analysis request you have about the image.
  • Example prompts
    • What is in this image?
    • Describe the main elements of this screenshot.
    • What is the person in this image doing?
    • Can you tell me about the product shown in this picture?
change_image_aspect_ratio – Changes the aspect ratio of existing images. Maintains all visual content while extending to fit the new ratio. Supports standard ratios (1:1, 4:3, 16:9, 9:16) and custom ratios (for example, 3:2, 21:9, 5:4).
  • When to use
    • When you need to change the aspect ratio of an existing image.
    • When you want to adapt an image to a specific display size or layout requirement (for examplee, for a social media post, website banner, or print).
    • When you explicitly request to "change the aspect ratio," "make it square," "widescreen," or similar.
  • Parameters
    • image_link – A single image file link to change the aspect ratio.
    • target_aspect_ratio – The desired target aspect ratio. Options include standard ratios like '1:1' (Square), '4:3' (Standard landscape), '16:9' (Widescreen landscape), '9:16' (Vertical portrait), or custom ratios such as '3:2', '21:9', '5:4', and so on.
    • number_of_images – The number of variations (integer, from 1 to 4) to generate for the new aspect ratio.
  • Example prompts
    • Change the aspect ratio of this image to 16:9.
    • Can you make this picture a square?
    • I need to resize this image to a 9:16 portrait format.
    • Adjust the aspect ratio of the image at 'link_to_image.jpg' to 3:2.
generate_or_edit_image – Generate new images from text descriptions or edit existing images. Supports style transfers, object manipulation, zoom, and more.
  • When to use
    • When you need to generate a new image based on a textual description.
    • When you want to edit an existing image, such as removing an object, changing the background, or adjusting lighting.
    • When you want to create multiple variations of an existing image.
    • When performing operations like style transfer, object addition, or artistic enhancement on an image
  • Parameters
    • prompt – A text description for image generation or detailed instructions for image modification.
    • image_links – A comma-separated string of image file links. This can be used for editing existing images or generating variations. The first image is considered primary, and additional images provide context.
    • number_of_images – The number of variations (integer, 1-4) to generate or edit.
    • edit_type – The type of edit operation for temperature optimization (edit mode only). Options include the following:
      • style_transfer
      • object_removal
      • object_addition
      • background_change
      • lighting_adjustment
      • color_correction
      • artistic_enhancement
      • aspect_ratio_change
    • historical_context – Previous conversation context or editing history (edit mode only).
  • Example prompts
    • Generate a picture of a futuristic city at sunset.
    • Edit this image to remove the person in the background.
    • Change the style of this photo to a watercolor painting.
    • Create three variations of this product image with different lighting.
    • Add a dog to the image at 'image_link_1'.
analyze_image_content – Uses AI to understand and analyze the content of images, including screenshots or images found through web searches, and answers questions based on the visual information.
  • When to use
    • When you have an image (for example, a screenshot or a generated image) and need to extract information or ask specific questions about its content.
    • To get a description or analysis of what is depicted in an image.
  • Parameters
    • file_id – The ID of the image file to be analyzed. This file should exist in the Opal backend (for instance, from a previous upload or generation).
    • query – The specific question or analysis request you have about the image (for example, What is the main subject? or Describe the colors used).
  • Example prompts
    • What is in this image?
    • Describe this product.
    • What is happening here?

Keywords

figure_out_search_keywords – Generates 8-15 related search keywords for comprehensive information about a topic, presented in a markdown table format.
  • When to use
    • When you need to determine effective keywords for a search based on a user's natural language query.
    • When you want to understand the core components of a  request to formulate precise search queries for other tools (like search_web or search_optimizely_docs).
    • To break down a complex query into actionable search terms.
  • Parameters
    • user_query – The query for which the search keywords need to be generated.
  • Example prompts
    • Figure out search keywords for "Optimizely product features and benefits".
    • What are the best keywords to search for information on "A/B testing best practices"?
    • Help me find search terms for "How to integrate Optimizely with Google Analytics".

Remote Development Environment (RDE)

rde_attach_instance – Attach an existing RDE instance to the conversation.
  • When to use
    • Connect an already running Remote Development Environment (RDE) to the current chat session.
    • Enable code_execute and workspace tools to interact with an existing codebase or development environment.
    • Reassign an active RDE instance from another conversation to the current one for continued work.
  • Parameters
    • instance_id – RDE instance ID to attach.
  • Example prompts
    • Please attach my existing RDE instance, for example, using the ID inst-12345.
    • Can you connect the dev environment we used yesterday to this chat, for example, instance inst-67890?
    • I want to run some code in my running RDE, for example, attach instance inst-abcde so we can continue debugging.
rde_create_instance – Create a new RDE instance from a template and attach it to this conversation.
  • When to use
    • Provision a brand new development environment based on a predefined template.
    • Download repository code and configure tools and runtimes for a new project in the workspace.
    • Initialize an RDE so you can start executing code or searching the codebase from scratch.
  • Parameters
    • name – Human-readable name for this instance.
    • template_id – Template ID from rde_list_templates tool.
  • Example prompts
    • Create a new development environment for the frontend project, for example, using template tmpl-react-app and name it "My React Dev".
    • I need a new RDE for data analysis, for example, use the tmpl-data-science template and call it "Data Workspace".
    • Please provision a new instance from the backend template, for example, named "API Service" with ID tmpl-node-backend.
rde_list_templates – List available RDE templates.
  • When to use
    • Discover what development environment templates are available to you before creating a new instance.
    • Review the pre-configured repositories, resources, runtimes, and tools available in different templates.
    • Find the correct template_id required for the rde_create_instance tool.
  • Parameters
    • No parameters required.
  • Example prompts
    • What RDE templates are available for me to use?
    • Can you list the development environment templates, for example, so I can find the one for Python projects?
    • Show me the available templates before I create a new instance.

Retrieval-Augmented Generation (RAG)

RAG tools only display on Opal instances where RAG is provisioned.

The search_application_data tool is retired. It has been replaced by the rag_retrieve_from_cmp tool.
rag_retrieve_from_cmp – Searches your Optimizely CMP data, campaigns, tasks, assets, work requests, and briefs, using semantic similarity and SQL-based queries. Returns results as structured data for use in conversation responses.
  • When to use
    • Finding specific campaigns, tasks, or assets in CMP.
    • Retrieving campaign briefs or task details.
    • Searching content across your CMP workspace by topic, label, or category.
    • Pulling context for content creation or planning.
    • Answering questions like "our blogs", "assets assigned to me", or "overdue tasks".
  • Parameters
    • query – Natural language description of the content to find. Example: "Find campaigns related to summer marketing".
    • (Optional) resource_types – Filter by resource type: asset, campaign, task, work_request.
    • (Optional) asset_types – Filter by asset type: image, video, pdf, article, and so on.
    • (Optional) status – Filter by status values such as On Hold, Overdue, In Progress, Done.
    • (Optional) assignees – Filter by assignee name, email, or ID.
    • (Optional) owners – Filter by owner name, email, or ID.
    • (Optional) creators – Filter by creator name, email, or ID.
    • (Optional) date_filters – Date range filters specifying a field, start date, and end date.
    • (Optional) field_filters – Custom field or label filters using a field ID and value.
    • (Optional) limit – Maximum number of results to return.
    • (Optional) chat_history – Previous conversation context for multi-turn queries.
    • (Optional) thread_id – Thread ID for conversation tracking.
    • (Optional) agent_execution_id – Agent execution ID for request tracing.
  • Example prompt
    • Show me all overdue tasks assigned to Sarah.
    • What campaigns are currently at risk?
    • Find all video assets created this month related to our product launch.
rag_retrieve_from_cmp_as_csv – Searches your Optimizely CMP data, campaigns, tasks, assets, work requests, and briefs, using semantic similarity and SQL-based queries. Returns results as tabular CSV data. 
  • When to use
    • When you want a table, spreadsheet, or CSV export of your CMP data.
    • The results need to be processed as structured tabular data.
  • Parameters
    • query – Natural language description of the content to find. Example: "All assets created in Q3".
    • (Optional) resource_types – Filter by resource type: asset, campaign, task, work_request.
    • (Optional) asset_types – Filter by asset type: image, video, pdf, article, and so on.
    • (Optional) status – Filter by status values such as On Hold, Overdue, In Progress, Done.
    • (Optional) assignees – Filter by assignee name, email, or ID.
    • (Optional) owners – Filter by owner name, email, or ID.
    • (Optional) creators – Filter by creator name, email, or ID.
    • (Optional) date_filters – Date range filters specifying a field, start date, and end date.
    • (Optional) field_filters – Custom field or label filters using a field ID and value.
    • (Optional) limit – Maximum number of results to return.
    • (Optional) chat_history – Previous conversation context for multi-turn queries.
    • (Optional) thread_id – Thread ID for conversation tracking.
    • (Optional) agent_execution_id – Agent execution ID for request tracing.
  • Example prompt
    • Export a table of all image assets tagged with 'brand' created last month.
    • Give me a report of all in-progress tasks assigned to the design team this quarter.
    • Export all work requests submitted in the last 30 days.
rag_retrieve_from_optimizely_graph – Search for relevant information in your CMP and CMS data using RAG for Optimizely Graph. The tool provides powerful search, filtering, and content delivery capabilities for your applications. The tool can return both structured documents (like content items) and unstructured analytical data, depending on your query.
  • When to use
    • Search for content across your Optimizely products (CMS, CMP).
    • Find specific content, such as articles, products, or experiments.
    • Get analytics or summary data from Optimizely Graph.
    • Power headless content delivery for mobile or web applications.
  • Parameters
    • query – Search query to find relevant application data in CMP or CMS.
    • (Optional) chat_history – Previous conversation context for better search results.
    • (Optional) thread_id – Thread identifier for conversation continuity.
  • Example prompts
    • Find content related to 'winter promotions'.
    • Show me analytics for the latest homepage experiment.
    • What features are enabled for US users?

Search

search_optimizely_docs – Searches Optimizely public documentation (end-user and developer documentation) and summarizes relevant content.
  • When to use
    • Understand how to perform a specific task within an Optimizely product.
    • Search the Optimizely knowledge base or documentation for answers to your questions.
    • Find steps, procedures, or details about product features that are likely covered in support documentation.
    • Clarify or supplement your understanding of a topic if you are unsure about an answer.
  • Parameters
    • query – The search query you want to use to find information in the Optimizely knowledge base.
  • Example prompts
    • How do I create a new experiment in Optimizely Web Experimentation?
    • Tell me about the different types of content in Optimizely CMS.
    • What are the steps to integrate Optimizely Feature Experimentation with a React application?
    • Search the documentation for information on A/B testing best practices.
    • I need to know how to set up metrics in Personalization.
search_web – Searches the web for a given query using Google.
  • When to use
    • Find general information, news, or external resources related to marketing, experimentation, or digital experience.
    • Look for best practices, industry trends, or competitive analysis that extends beyond Optimizely's product features.
    • Search for images or other media files.
    • Gather information from specific websites (site search).
    • Find definitions or explanations of general concepts.
  • Parameters
    • search_query – The main query you want to search for.
    • (Optional) num_results – The number (integer) of search results you want to retrieve.
    • (Optional) country_code – A two-letter ISO country code (for example, 'us' or 'gb') to localize your search results.
    • (Optional) exact_terms – A phrase that all documents in the search results must contain.
    • (Optional) exclude_terms – A word or phrase that must not appear in the search results.
    • (Optional) file_type – If you are looking for specific file formats (for example, 'pdf' or 'docx').
    • (Optional )site_search – Specifies a particular website to include or exclude from the search results (for example, 'optimizely.com').
    • (Optional) search_type – Set to 'image' if you are looking for images.
      • (Optional) image_size – If search_type is 'image', you can specify the desired image size (for example, 'large', 'medium', or 'icon').
      • (Optional) image_type – If search_type is 'image', you can specify the desired image type (for example, 'photo', 'clipart', or 'face').
  • Example prompts
    • What are the latest trends in e-commerce personalization?
    • Find articles about A/B testing strategies.
    • Search for images of successful landing page designs.
    • What is the definition of 'customer lifetime value'?
    • Find information on optimizely.com about feature flags.
    • Search for marketing automation tools, excluding HubSpot.

Skills management

create_or_edit_skill – Create or edit a personal or organization-level skill in Opal.
  • When to use
    • Save the current conversation or instructions as a new personal skill, for example, to reuse specific formatting rules.
    • Edit an existing skill, for example, to update its title, content, or add a shortcut handle.
    • Make a set of instructions available organization-wide by creating an organization skill.
  • Parameters
    • skill_type – personal for individual use or org for organization-wide visibility. Defaults to personal for new skills unless specified. For edits, the tool preserves the original type. Type changes require creating a new skill.
    • (Optional) active – Whether the skill is active in chat. New skills are active by default. On edits, omit unless explicitly changing. Omitting preserves the existing state.
    • (Optional) files – Files to attach to this skill as a mapping of filename to file reference. Each entry must have file_id and mime_type. For example, {"report.pdf": {"file_id": "193364b6-79e9-42e9-be7e-831c819598xx", "mime_type": "application/pdf"}}. On edits, omit to preserve existing attached files.
    • (Optional) instance_id – Instance ID to scope the skill. On edits, omitted unless explicitly changing. Omitting preserves the existing value.
    • (Optional) mention_handle – Shortcut handle for invoking this skill in chat, without the / prefix. For example, translate-dothraki. Must be lowercase alphanumeric with hyphens. If a conflict occurs on save, the tool informs you and suggests an alternative.
    • (Optional) product_sku – Product SKU to scope the skill. 
    • (Optional) skill – Full skill text derived from the conversation. Written as a self-contained directive the agent can follow, including which tools to use and how. Required when creating a new skill. On edits, omitted unless explicitly changing. Omitting preserves the existing skill content.
    • (Optional) skill_id – Existing skill GUID for edits. Omit to create a new skill.
    • (Optional) title – Concise human-readable name for the skill. For example, Translate to Dothraki. Separate from the mention_handle parameter. Required when creating a new skill. On edits, omitted unless explicitly changing. Omitting preserves the existing title.
    • (Optional) trigger_conditions – Human-readable description of when to apply this skill, inferred from context.
    • (Optional) trigger_tools – Tools whose presence in the session automatically activates this skill.
    • (Optional) trigger_type – How this skill is activated.
      • keyword triggers on matching phrases
      • tool triggers when specific tools are present in the session.
    • (Optional) update_summary – Brief summary of changes when editing, in present tense. For example, Add shortcut or Update skill content.
  • Example prompts
    • Save this entire conversation as a skill, for example, naming it "Weekly Report Generator".
    • Edit my AmaWaterways skill, for example, by updating the instructions to include a new formatting rule.
    • Add a shortcut to my editing skill, for example, using the handle "edit-docs".
find_skill – Search existing Opal skills by free-text query. Read-only.
  • When to use
    • Locate a specific skill you referenced by name or shortcut, for example, so you can edit it.
    • Check if a similar skill already exists before creating a new one, for example, to avoid duplicates.
    • Search through your personal or organization skills to find an active skill set.
  • Parameters
    • query – Free-text query matched as a case-insensitive substring against each skill's title, content, and shortcut. Whitespace-separated terms are ANDed together. Prefer a single distinctive keyword over a full phrase.
    • (Optional) kind – Restrict the search to personal or organization skills. Omit to search both (subject to permissions).
  • Example prompts
    • Find my skill related to daily standups, for example, searching for the keyword "standup".
    • Check if there is an organization skill for translating text, for example, querying "translate".
    • Can you locate the skill I use for formatting markdown, for example, so we can edit it?
get_skill – Fetch the full definition of a single Opal skill by its GUID. Read-only.
  • When to use
    • Retrieve the full content and definition of a skill using its GUID, for example, after locating it with the find_skill tool.
    • Check a skill's current configuration before proposing an update, for example, so you can compute the exact edit needed.
    • Review the specific instructions saved inside a personal or org skill.
  • Parameters
    • skill_guid – The GUID of the skill to fetch (the skill_guid returned by the find_skill tool).
  • Example prompts
    • Fetch the full definition of the skill, for example, using the GUID 123e4567-e89b-12d3-a456-426614174000.
    • Get the current details of my writing skill, for example, so we can modify the tone instructions.
    • Can you retrieve the organization skill content, for example, by passing its specific skill_guid?

Webpage analysis

analyze_pagespeed – Analyze a webpage's performance, SEO, or accessibility using Google PageSpeed Insights. 
  • When to use
    • Before launching a new webpage or website, to ensure it meets performance, SEO, and accessibility standards.
    • When a webpage is experiencing slow loading times, high bounce rates, or poor user engagement, to identify underlying technical issues.
    • To regularly check and improve the accessibility of a website, ensuring it is usable by individuals with disabilities.
    • To identify technical SEO opportunities and issues that might be impacting search engine rankings.
    • After implementing performance or SEO improvements, to verify their effectiveness and measure the impact.
  • Parameters
    • url – The URL of the webpage to analyze.
    • analysis_type – The type of audit to perform. It can be one of the following:
      • 'seo_audit' – Technical SEO analysis with performance metrics (SEO + Performance categories).
      • 'accessibility' – Accessibility audit (WCAG/ARIA compliance).
      • 'page_speed' – Page speed and performance analysis (Performance + Best Practices categories).
    • (Optional) device – The device to emulate for the analysis. It can be 'desktop' or 'mobile'.
  • Example prompts
    • Can you run a page speed analysis for https://www.optimizely.com on mobile?
    • I need an SEO audit for my new product page at https://www.example.com/products/new-product.
    • Check the accessibility of our homepage https://www.mycompany.com.
    • Give me a performance report for https://blog.optimizely.com on desktop.
    • Perform an SEO and performance audit for https://www.marketingcampaign.com/landing-landing-landing-landing.page.

System tools in beta

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.

Video

The video tools are in beta. Contact your Customer Success Manager for more information.
generate_video – Generates videos from text descriptions and optional starting images. It supports various aspect ratios and durations, and includes automatic prompt enhancement and audio generation.
  • When to use
    • Create a new video based on a textual description.
    • Generate a video using an existing image as a starting point.
    • Produce video content for marketing, social media, or other digital experiences.
    • Experiment with different video styles, durations, or aspect ratios.
  • Parameters
    • prompt – A text description of the video you want to generate.
    • (Optional) starting_image_link – The URL or link to a starting image to be used for image-to-video generation.
    • (Optional aspect_ratio – The aspect ratio of the video. Options include '16:9' (Widescreen), '9:16' (Portrait), or '1:1' (Square). If not specified, it defaults to '16:9'.
    • (Optional) duration_seconds – The desired duration of the video in seconds. Options are 4 or 8. If not specified, it defaults to 8 seconds.
    • (Optional) generate_audio – Set to True to include audio generation in the video. If not specified, it defaults to True.
    • (Optional) generation_mode – Determines the balance between generation speed and quality. Options are 'standard' or 'fast'. If not specified, it defaults to 'standard'.
    • (Optional) number_of_videos – The number of video variations to generate. You can request 1 or 2 variations. If not specified, it defaults to 1.
    • (Optional) resolution – The resolution of the video. Options are '1080p' or '720p'. If not specified, it defaults to '1080p'.
  • Example prompts
    • Generate a video of a futuristic city at sunset.
    • Create a 16:9 video, 8 seconds long, showing a product being unboxed.
    • Generate a video from this image: https://example.com/image.jpg with a prompt about a serene forest.
    • Make a short portrait video (9:16) of a person dancing.
    • Generate two variations of a video about a new software feature.

User input

The user input tools are in beta. Contact your Customer Success Manager for more information.
ask_agent_input – Collects a specialized agent's required parameters from the user before execution by presenting a structured input form in the chat interface.
  • When to use
    • You @mentions a specialized agent but has do not provide all required parameters.
    • Collect structured inputs for an agent that requires multiple fields before it can run.
    • Pre-populate a form with known values so the user only needs to fill in the remaining fields.
    • Gather file uploads, boolean flags, and text inputs together in a single form before agent execution.
  • Parameters
    • agent – JSON object with agent info. Must have name and description. Optionally include agent_id and is_system_agent (boolean).
    • parameters – JSON array of parameter objects. Each object must have: name, description, type, required (boolean). Optionally include placeholder, value Example: [{"name": "Campaign Name", "description": "Name of the campaign", "type": "string", "required": true, "placeholder": "for example, spring-sale"}, {"name": "Source Document", "description": "PDF or text to summarize", "type": "file", "required": true}]
  • Example prompts
    • Run the UTM Creation agent to build a tracking link for our upcoming webinar.
    • I want to use the Campaign Brief Generator agent, can you collect the inputs I need to provide?
    • Launch the SEO Analyzer agent on my landing page draft.
    • Use the Image Resizer agent to resize my banner. I’ll upload the file now.
    • Kick off the Audience Segment Builder agent for our EMEA campaign.
ask_user_question – Presents the user with one or more structured questions and selectable options to gather input before proceeding with a task.
  • When to use
    • A request is ambiguous and requires clarification before taking action.
    • Present the user with a defined set of options to choose from instead of asking open-ended questions.
    • Gather preferences, such as tone, format, or target audience, before generating content.
    • Let users select multiple applicable options, for example the channels a campaign should target.
    • Resolve ambiguity when two or more valid approaches exist and a user preference determines the correct path.
  • Parameters
    • questions – JSON array of question objects. Each object must have the following: question, type, and options. Example: [{"question": "What is your goal?", "type": "single_select", "options": ["A", "B"]}]
  • Example prompts
    • I need a blog post. Can you ask me what tone and audience I want before you start writing?
    • Before creating the campaign brief, ask me which channels and goals apply.
    • Help me choose the right experiment type for my homepage redesign.
    • Ask me which content formats I want before building the editorial calendar.
    • I’m not sure what kind of report I need. Can you ask me a few questions first?

Content display

The content display tools are in beta. Contact your Customer Success Manager for more information.
present_images – Displays generated or edited images to the user as a rich visual card in the chat interface. Call this tool after generate_or_edit_image when images are the final output.
  • When to use
    • Display the results of an image generation or editing task as the final deliverable.
    • Present a collection of image variants, for example, multiple hero image options for a campaign, in a carousel or grid.
    • Show a single generated image after applying edits such as style transfer, object manipulation, or aspect ratio changes.
    • Surface a set of branded visuals so the user can review and select a preferred option.
  • Parameters
    • image_links – Ordered list of image file links from the generate_or_edit_image tool results.
    • title – Short five to six word title for the image collection. Sentence case, no quotes.
  • Example prompts
    • Generate three hero image variants for our Spring 2026 campaign and show them to me.
    • Create a product shot on a white background and display it.
    • Edit this banner image to remove the background, then show me the result.
    • Generate a 16:9 social media graphic for our webinar and present it.
    • Show me four variations of our logo on a dark background.
present_files – Present files to you with a rich visual card.
  • When to use
    • Display the final generated document or data file requested by you.
    • Display a rich visual carousel of images generated or edited during the conversation.
    • Present a collection of outputs, for example, a chart and a report clearly with download links.
  • Parameters
    • files – JSON array of file objects. Each object must have the following: 
      • name – String, the filename including its extension. For example, chart.png, plan.md, or deck.pptx.
      • (Optional) mime_type – String.
      • Each object must also have one of the following to identify the file: 
        • path – Workspace path from the code_execute tool. For example, output/chart.png from workspace_files[].path. 
        • file_id – File-server UUID. The file_id from FileMetadata or the file_link from link from FileMetadata 
      • Examples code_execute – [{"name": "chart.png", "path": "output/chart.png", "mime_type": "image/png"}].
      • Example file-server – [{"name": "hero.png", "file_id": "abc-123", "mime_type": "image/png"}].
      • Example with link – [{"name": "report.pdf", "file_link": "https://.../v1/file/abc-123"}].
    • title – Short five to six word title for the file collection. Sentence case, no quotes.
    • (Optional) display_mode – How to display the files. Use carousel when all files are images. Use list for documents, data files, or mixed types.
  • Example prompts
    • Present the generated report file, for example, so I can review and download the PDF.
    • Show the three newly created hero images, for example, using the carousel display mode.
    • Can you display the data files, for example, providing the title "Q3 Financial Data Export"?
present_widget – Renders a data widget, such as a chart, table, metric card, or card list inline in the chat interface.
  • When to use
    • Render a structured data table or metric summary card directly in the chat.
    • Present a dashboard-style visualization, for example, campaign performance by channel, after executing analysis code.
    • Surface aggregated experiment results or A/B test metrics in a visual card format.
  • Parameters
    • element_id – Space-Elements element ID.
    • space_id – Space-Elements space ID.
    • title – Display title for the widget.
  • Example prompts
    • Show me a bar chart of our experiment results by variation for Q2 2026.
    • Generate a table summarizing campaign performance by channel and display it in chat.
    • Create a metric card showing our current conversion rate and present it.
    • Visualize the revenue breakdown by product category as a pie chart.
    • Build a dashboard card showing weekly active users over the last 30 days.

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.