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.
{
"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_memorytool 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_memorytool, and chat modes or agents that still refer toclear_memoryuse this tool instead.
- Tools that Retrieve Content
-
get_document_content- Retrieves content from the document specified by the provided URL. An optional
lineNumberingparameter 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
lineNumberingparameter 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_agentstool.
- 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.