Tool Calls

Within the definition of custom actions for the AI Positron, you can reference existing functions that are called by the AI engine to interact with the application. This gives actions more context information and generates more accurate responses from the AI.

Here is an example of a tool reference that gets called by the AI engine to obtain the entire contents of the document:

{
    "id": "action.summarize",
    "title": "Summarize",
    "categoryId": "Overview",
    "output-type": "none",
    "description": "Generate a summary of the selected content or the entire document.",
    "prompt": "Your task is to summarize the provided user text.",
    "parameters": {
        "function_refs": [
            {
                "ref": "get_current_document_text"
            }
        ]
    }
}

The current available tool reference values are:

Tools that Change Content

add_dita_reference_to_ditamap (Not Available for Web Author): Modifies the DITA map currently opened in the DITA Maps Manager view and adds a topic reference to it.
save_document: Saves the document at the specified path and writes content to it. If a resource already exists at the specified URL, the content of the document will be overwritten with the new content. For actions that use this tool, the application gathers a list of resources to modify and displays them in a Preview dialog box after the action processes.
edit_document: Performs exact string replacements in a specified file. The AI can use this lightweight tool to make a small number of precise changes in a document. In the desktop application, this tool also provides parameters that allow the LLM to force change tracking and specify a reviewer's name for XML documents open in the Author visual editing mode.
copy_move_rename_path (Not Available for Web Author): Copies, moves, or renames a local file or folder path. When used in Oxygen 28.1 or newer, if the Main Files feature is enabled in the application, references to the moved or renamed resource are automatically updated.

Tools that Retrieve Content

get_document_content: Retrieves content from the document specified by the provided URL. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
get_current_document_location: Retrieves the location (absolute path/URL) of the current file that is open in the editor.
search_project_resources (Works with Oxygen desktop 27 or newer, Content Fusion 8.1 or newer, not Available for Web Author): Retrieves (in JSON format) a set of resources from the user's local project based on the search keywords. When using Oxygen XML 28 and newer, the AI can specify the page size, current page, and whether to search for documents that contain all keywords or only part of the keywords.
get_binary_resource_description: Describes the contents of a binary resource (image, PDF, DOCX, PPTX, or XSLX) by invoking an agent with a custom prompt and location of the resource.
grep_project (Works with Oxygen desktop 28 or newer, Content Fusion 9.0 or newer, Not Available for Web Author): Retrieves (in JSON format) a set of precise matches found in the project for a searched text. The search can be done with regular expressions enabled or by setting file name and XPath filters. The maximum number of precise matches that can be returned is 50, but the returned result also contains the total number of project-wide matches and a counter of matches per resource, giving the AI a better overview.
list_dir (Works with Oxygen desktop, Not Available for Content Fusion and Web Author): Lists the contents of a folder/directory path.
search_webhelp_content: Returns content from the associated Oxygen Feedback WebHelp system that has external RAG sources enabled and configured.
search_oxygen_feedback_site_content: Returns content from the specified Oxygen Feedback WebHelp token passed as a parameter. The Enable External RAG Sources checkbox must be selected in the Tools and RAG preferences.
get_current_document_markup: Retrieves all text with markup from the current document open in the editor. An optional lineNumbering parameter allows the AI to request the returned content to be returned with line numbers included.
get_current_document_text: Retrieves all plain text (e.g. without markup) from the current document open in the editor.
get_schematron_components (Not Available for Web Author or Content Fusion): Retrieves Schematron components (e.g. pattern, title, phase, diagnostics) used in the provided code, defined in both the current file and any imported or included stylesheets.
get_xsd_components (Not Available for Web Author or Content Fusion): Retrieves XML schema components (e.g. simpleType, elements, notations, complexType, attributes, groups) used in the provided code, defined in both the current file and any imported or included stylesheets.
get_ditamap_structure (Works in Oxygen desktop, Content Fusion 8.1 or newer, Not Available for Web Author): Returns a hierarchical structure of the DITA map that is currently open in the DITA Maps Manager view. This structure shows the selected topic and provides context, including its parent, siblings, descendants, and nearby nodes within the DITA map. This feature helps the AI understand where the topic is located in relation to other elements in the DITA map. If the selected topic cannot be identified, the hierarchy will start from the root of the DITA map.
resolve_dita_reference (Not Available for Web Author or Content Fusion): Resolves a DITA XML key reference (e.g. <ph keyref="abc"/>), content key reference (e.g. <uicontrol conkeyref="abc"/>), or content reference (e.g. <uicontrol conref="abc"/>).
find_reusable_components (Works only in Oxygen Desktop version 27 or newer): Returns a list of DITA XML reusable components that match the keywords.
get_dita_keyrefs (Not Available for Web Author or Content Fusion): Returns a mapping between product names and corresponding DITA key references in JSON format.
evaluate_xpath: Evaluates an XPath 2.0 expression against an XML document and returns the matching results in JSON format. Use it to inspect document structure, extract element or attribute values, count or filter nodes, verify specific content, or locate elements before editing them. For node matches, each result can include the matched XML content together with its location in the source, helping the AI work with structured content without reading the entire file. If no document URL is provided, the expression is evaluated against the currently open document. Otherwise, the specified document is evaluated even if it is not open.

Tools to Validate or Change XML Structure

validate_and_check_for_completeness: Invokes a validate and check for completeness check with settings provided by the LLM on a DITA map or DITA-OT project file.
validate_content: Validates specified content and reports error messages in JSON format.
validate_current_document: Validates the current document's content and reports error messages in JSON format.
validate_with_schematron (Works with Oxygen version 29 or newer): Generates rules from user-provided requirements and uses them to validate documents.
get_xml_refactoring_operations (Works with Oxygen version 28 or newer, not Available for Web Author or Content Fusion): Provides the AI with a list of all XML refactoring operations (ID, name, description) defined in the application.
get_xml_refactoring_operation_params (Works with Oxygen version 28 or newer, not Available for Web Author or Content Fusion): Provides the required parameters list for a specific XML operation ID.
refactor_xml (Works with Oxygen version 28 or newer, not Available for Web Author or Content Fusion): Invokes a specific XML refactoring operation on a specific XML content with specific AI provided parameters.
refactor_xml_with_xslt (Works with Oxygen version 28 or newer, not Available for Web Author or Content Fusion): Uses an XSLT stylesheet provided by the AI to process and modify the XML content.

Tools for Transformation Scenarios

invoke_transformation_scenario (Works only in Oxygen desktop): Runs a specified transformation scenario (or the scenario associated with the current editor if the name is not specified). It returns a report that contains the status of the transformation, the tabs produced in the Results view, and the locations of the output files written to disk.
list_transformation_scenarios (Works only in Oxygen desktop): Lists the transformation scenarios that are available for the current editor.
get_results-messages (Works only in Oxygen desktop): Retrieves the content of specified tabs (by name) from the Results view.

Tools to Invoke AI Actions or Agents

retrieve_ai_actions: Gets IDs and descriptions for each available AI action.
invoke_ai_action: Invokes an action by passing the action ID and content to process.
Tip:
To define actions that are hidden in the interface and intended only for use by other actions, prefix their IDs with agent.hidden.action.
retrieve_ai_agents: Gets IDs and descriptions for each available AI agent. Agents are AI actions that have the "output-action": "agentic" property set on them.
invoke_ai_agent: Invokes an AI agent by passing the agent ID and instructions. You can retrieve the available agent IDs by using the retrieve_ai_agents tool.

Tools for User Interaction

ask_user: Asks the user one or more clarifying questions, each with a set of suggested answers, and waits for a reply before the AI continues.

Multi Purpose Tools

run_command_line (Works only in Oxygen desktop).: Starts a command process on behalf of the user. The tool needs explicit user approval when it is invoked. The LLM can pass both the command line and extra environmental variables using this tool.

You can impose a description for the referenced tool that is called by the AI engine:

"function_refs": [
  {
      "ref": "get_current_document_text",
      "description": "The tool is designed to retrieve the complete document as 
      plain text without markup."
  }
]