Establish connection to the Universe/UniData server.

Uses configuration from environment variables:

• U2_HOST: Server hostname

• U2_USER: Username

• U2_PASSWORD: Password

• U2_ACCOUNT: Account name

• U2_SERVICE: Service type (uvcs/udcs), defaults to uvcs

Returns: Connection status and details including host, account, service, and timestamp.

Close all connections to the Universe/UniData server.

Returns: Disconnection status and count of closed connections.

List all active database connections.

Returns: List of active connections with their details (name, host, account, service, connection time, and active status).

Get the connection watchdog status and statistics.

The watchdog monitors connection health and automatically recovers from hung database connections.

Returns: Watchdog configuration and statistics including check counts, failure counts, and forced reconnects.

List all dictionary items for a Universe file.

Returns D-type (data), I-type (calculated), and other field definitions from the file's dictionary.

Args: file_name: Name of the Universe file include_system: If True, include system dictionary items (@ prefixed)

Returns: Dictionary containing file name, list of dictionary items with their types, and total count.

Get detailed definition for a specific dictionary field.

Returns the complete field definition including type, field number, conversion code, format, heading, and other attributes.

Args: file_name: Name of the Universe file field_name: Dictionary field/item name

Returns: Detailed field definition or error if not found.

Get a comprehensive description of a Universe file.

Combines file statistics with dictionary information to provide full context about the file structure. Useful for understanding data structure before querying.

Args: file_name: Name of the Universe file

Returns: Dictionary containing file stats, field definitions, and counts.

Analyze file structure by sampling records to infer field usage patterns.

Samples records from the file to detect:

• Which fields are populated

• Multivalue patterns

• Data types and common values

Useful when dictionary is incomplete or for understanding actual data usage.

Args: file_name: Name of the Universe file to analyze sample_size: Number of records to sample (default 100)

Returns: Analysis results including field usage statistics and patterns.

Get information about the current Universe account.

Returns account-level metadata including available files, VOC entries, and system information.

Returns: Dictionary containing account information, file list, and system details.

List available files in the current Universe account.

Args: pattern: File name pattern to match (supports * wildcard). Default "*" lists all files.

Returns: Dictionary containing list of matching file names and count.

Read a single record from a Universe file.

The record is returned with fields parsed into structured JSON, preserving multivalue and subvalue structure.

Args: file_name: Name of the Universe file record_id: Record ID (key) to read

Returns: Dictionary containing record id, fields (by number), and optionally the raw record data. Returns error if record not found.

Read multiple records from a Universe file efficiently.

Args: file_name: Name of the Universe file record_ids: List of record IDs to read

Returns: Dictionary containing file name, list of records, count, and any errors. Each record includes id and fields. Records not found are listed in errors.

Write or update a record in a Universe file.

Args: file_name: Target file name record_id: Record ID to create or update fields: Field values as JSON object. Keys are field numbers as strings, values can be strings (single value), lists (multivalues), or nested lists (subvalues). confirm: Must be True to execute the write. This is a safety measure.

Returns: Status of the write operation. Requires confirm=True to execute. Disabled in read-only mode.

Example fields: {"1": "John Doe", "2": ["555-1234", "555-5678"], "3": "CA"}

Delete a record from a Universe file.

Args: file_name: Target file name record_id: Record ID to delete confirm: Must be True to execute the delete. This is a safety measure.

Returns: Status of the delete operation. Requires confirm=True to execute. Disabled in read-only mode.

Get information about a Universe file.

Returns file statistics including type, modulo, separation, and record count.

Args: file_name: Name of the Universe file

Returns: Dictionary containing file statistics and metadata.

Export records from a Universe file to JSON format.

Reads the specified records and returns them as a JSON string. Useful for data analysis and integration with other tools.

Args: file_name: Name of the Universe file record_ids: List of record IDs to export expand_mv: If True, expand multivalues into separate objects. If False (default), preserve multivalue arrays.

Returns: Dictionary containing: - status: success or error - format: "json" - record_count: Number of records exported - data: JSON string of the exported records

Export records from a Universe file to CSV format.

Reads the specified records and returns them as a CSV string. Useful for spreadsheet import and data analysis.

Args: file_name: Name of the Universe file record_ids: List of record IDs to export expand_mv: If True, expand multivalues into separate rows. If False (default), join multivalues with delimiter. mv_delimiter: Delimiter for multivalues when expand_mv=False. Default is "|".

Returns: Dictionary containing: - status: success or error - format: "csv" - record_count: Number of records exported - row_count: Number of rows in CSV (may differ if expand_mv=True) - data: CSV string of the exported records

Save learned information about the Universe database.

Use this to persist useful discoveries about the database schema, file structures, query patterns, and data meanings. This information will be available in future conversations.

Good things to save:

• File purposes (e.g., "AR-CUST contains customer master records")

• Field meanings (e.g., "In CUSTOMERS, field 1 is name, field 5 is phone")

• Working query patterns that produced good results

• Relationships between files

• Data format notes (date formats, codes, etc.)

Args: topic: A short descriptive name for this knowledge (e.g., "CUSTOMERS file", "Invoice queries", "Date formats") content: The knowledge to save. Use markdown formatting. append: If True, add to existing topic. If False, replace it.

Returns: Status of the save operation.

Examples: save_knowledge("AR-CUST file", "Customer master file. Key is customer number.") save_knowledge("Date formats", "Dates stored as internal format. Use D2/ conversion.")

List all saved knowledge topics.

Returns a list of topics that have been saved about this database. Use get_knowledge_topic to retrieve the full content of a specific topic, or get_all_knowledge to retrieve everything at once.

Returns: Dictionary containing list of topics with summaries.

Get ALL saved knowledge about this Universe database.

IMPORTANT: Call this tool at the start of conversations to retrieve previously learned information about the database. This includes:

• File descriptions and purposes

• Field definitions and meanings

• Working query patterns

• Relationships between files

• Data format notes and conventions

This knowledge was saved from previous conversations to help you work more efficiently with this specific database.

Returns: All saved knowledge as markdown text.

Get saved knowledge for a specific topic.

Retrieves the full content of a previously saved knowledge topic.

Args: topic: The topic name to retrieve.

Returns: The topic content or error if not found.

Search saved knowledge for specific information.

Searches all saved knowledge for mentions of the query string. Useful for finding previously learned information about specific files, fields, or concepts.

Args: query: Text to search for (case-insensitive).

Returns: List of matching topics and relevant lines.

Delete a saved knowledge topic.

Removes a topic from the knowledge base. Requires confirmation.

Args: topic: The topic name to delete. confirm: Must be True to execute the deletion.

Returns: Status of the delete operation.

Execute a RetrieVe/UniQuery statement and return results.

Supports read-only query commands: LIST, SELECT, SORT, COUNT, SUM, SSELECT. Results are limited by max_rows parameter or the U2_MAX_RECORDS configuration.

Args: query: RetrieVe/UniQuery statement Examples: - 'LIST CUSTOMERS WITH STATE = "CA"' - 'SELECT ORDERS WITH ORDER.DATE >= "01/01/2024" BY ORDER.DATE' - 'COUNT INVOICES WITH STATUS = "OPEN"' max_rows: Maximum rows to return (optional, defaults to U2_MAX_RECORDS)

Returns: Dictionary containing query, output, status, and row limit applied.

Execute a TCL/ECL command and return the output.

TCL (Terminal Control Language) commands provide system-level operations. Dangerous commands are blocked by the safety validator. Some commands are disabled in read-only mode.

Args: command: TCL/ECL command to execute Examples: - 'WHO' - Show current user info - 'DATE' - Show current date - 'LISTFILES' - List available files - 'FILE.STAT CUSTOMERS' - Show file statistics

Returns: Dictionary containing command, output, and status. Returns error if command is blocked.

Execute a SELECT statement and return the list of record IDs.

This is useful for getting a list of matching records for further processing, without retrieving the full record data.

Args: query: SELECT or SSELECT statement Example: 'SELECT CUSTOMERS WITH STATE = "CA"' max_ids: Maximum IDs to return (optional, defaults to U2_MAX_RECORDS)

Returns: Dictionary containing query, list of record IDs, count, and whether results were truncated.

Validate a RetrieVe/UniQuery statement before execution.

Checks query syntax and safety without executing it. Useful for validating AI-generated queries before running them.

Args: query: Query statement to validate

Returns: Dictionary containing validation results: - valid: Boolean indicating if query is valid - command: The query command detected (LIST, SELECT, etc.) - warnings: List of potential issues - suggestions: Helpful hints for common patterns

Call a cataloged BASIC subroutine with arguments.

Executes a cataloged BASIC program and returns the results. Arguments are passed by reference, so output arguments will be returned in the response.

Args: name: Name of the cataloged subroutine args: List of argument values to pass (input arguments). Arguments are passed as strings and converted by the subroutine. num_args: Total number of arguments the subroutine expects. If not specified, uses len(args). Required if subroutine has output-only arguments.

Returns: Dictionary containing: - status: success or error - args_out: List of argument values after subroutine execution - original_args: The input arguments that were passed

Example: # Call GET.CUSTOMER.DATA with customer ID, returns data in args 2-3 call_subroutine("GET.CUSTOMER.DATA", ["CUST001", "", ""], num_args=3)

List available cataloged programs in the account.

Searches the system catalog for programs matching the pattern. This includes BASIC subroutines that can be called with call_subroutine.

Args: pattern: Program name pattern (supports * wildcard). Default "*" lists all cataloged programs.

Returns: Dictionary containing list of program names and count.

Begin a database transaction.

Starts a new transaction. All subsequent write operations (write_record, delete_record) will be part of this transaction until commit_transaction or rollback_transaction is called.

Returns: Dictionary containing: - status: success or error - in_transaction: True if transaction is now active - started_at: Timestamp when transaction started

Note: Only one transaction can be active at a time. Attempting to start a new transaction while one is active will fail.

Commit the current transaction.

Saves all changes made since begin_transaction was called. The transaction is closed after commit.

Returns: Dictionary containing: - status: success or error - in_transaction: False after successful commit - message: Confirmation message

Note: If no transaction is active, returns an error.

Rollback the current transaction.

Discards all changes made since begin_transaction was called. The transaction is closed after rollback.

Returns: Dictionary containing: - status: success or error - in_transaction: False after successful rollback - message: Confirmation message

Note: If no transaction is active, returns an error.

Get the current transaction status.

Returns information about whether a transaction is active and when it was started.

Returns: Dictionary containing: - in_transaction: True if transaction is active - started_at: Timestamp when transaction started (if active) - read_only_mode: Whether server is in read-only mode