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.
store_to_memory (Not Available for Web Author)
Records a user preference or directive in persistent global memory so it can be considered in future interactions across projects. When the new preference contradicts or refines a rule that is already stored, the AI replaces that rule with the update_memory tool instead of storing a second one.
update_memory (Not Available for Web Author)
Changes the rules stored in the persistent memory used for AI interactions. It can forget a single rule, revise the wording of a single rule, or clear the entire memory. The AI asks for confirmation before clearing the memory. This tool replaces the clear_memory tool, and chat modes or agents that still refer to clear_memory use this tool instead.
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.
search_chat_history (Works only in Oxygen desktop, Not Available for Web Author, Eclipse, or Content Fusion)
Searches the titles and descriptions of conversations saved in the current project's chat history to find a past conversation you refer to (for example, "we discussed this before, what was the conclusion?"). A conversation matches if its title or description contains at least one search word, ignoring case and accents. Matches are ranked by the number of matching words they contain, with the most recently changed conversations listed first when the number of matching words is the same. The conversation in which the tool is called is never included. The AI receives at most 15 matches, each with its title, description, creation date, last modification date, and number of messages, along with the total number of matches. This lets it determine when a search was too broad. The tool does not search conversation messages. The AI uses the titles, descriptions, and dates to answer or asks you to reopen the conversation. Because past conversations may contain content that you did not intend to share again, the chat asks for your confirmation before running the search. You can also add the tool to the list of tools that are always allowed (see Unsafe Tool Auto-Approval Preferences).
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.
find_possible_reusable_content (Works only in Oxygen desktop version 29 or newer, Not Available for Web Author or Content Fusion)
Returns groups of elements with similar text content that are candidates for content reuse. The AI can choose the elements to search, the project, folder, or file to search (by default, the current project or, if no project is open, the resources referenced by the DITA map open in the DITA Maps Manager view), whether to ignore common stop words, and the number of groups to return. It can also limit the results to groups found in specific documents. With an Enterprise license, the AI can lower the minimum similarity between elements, although this makes the search take longer. HTML files are skipped.
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.
get_profiling_conditions (Works only in Oxygen desktop version 29 or newer, Not Available for Web Author or Content Fusion)
Returns (in JSON format) the profiling (conditional text) configuration for a document. This includes the profiling attributes and allowed values for each of them, the defined profiling condition sets, the currently applied condition set, and how profiled content is currently displayed in the editor. The attributes and values come from the Profiling/Conditional Text preferences or from a DITA subject scheme map referenced in the root map. The AI uses this tool to add or change profiling attributes using only the declared attributes and values, and to explain why some content is excluded or missing from the output. An optional document URL can be specified (the document does not need to be open). Otherwise, the current document opened in the current editor or the current DITA map in the DITA Maps Manager view is used as context.
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.
compare_documents (Works only in Oxygen desktop version 29 or newer, Not Available for Web Author or Content Fusion)
Returns the differences between two documents in unified diff format. Without parameters, it reports the comparison currently open in the editing area, including unsaved modifications. Otherwise, it compares two specified documents without opening them and can optionally use a common ancestor for a three-way comparison. The AI uses this tool to summarize changes between two versions of a document, explain a change, or answer questions about a comparison.
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."
  }
]

Tools Contributed by Oxygen Add-ons

Batch Documents Converter

If Oxygen's Batch Documents Converter add-on version 6.2.0 or later is installed, it contributes the following tool for AI Positron:

convert_documents
Converts one or more documents between supported formats. It accepts either a single file or an entire folder as input and converts the contents to the specified output format.
Terminology Checker

If Oxygen's Terminology Checker add-on version 4.2.2 or later is installed, it contributes the following tools for AI Positron:

term_check_document_content
Checks a specified document's content to identify terminology issues.
term_check_current_document
Checks the currently open document's content to identify terminology issues.