Agent Tools & Capabilities

Introduction

The OpsHub Agent System provides 144+ specialized tools that enable AI agents to automate investment operations workflows. These tools transform natural language requests into concrete actions across spreadsheets, databases, dashboards, compliance systems, and more.

Why Tools Matter: Tools are the hands and eyes of AI agents. Without tools, agents can only talk. With tools, they can read data, write reports, validate compliance, create dashboards, and orchestrate complex workflows.

Tool Execution Model

Key Characteristics:

Tenant-Isolated: Every tool call is scoped to the user’s organization and team
Audited: All tool executions are logged to audit.audit_log for compliance
Type-Safe: Pydantic schemas ensure valid parameters
Context-Aware: Tools access workspace context (active portfolio, date, page)
Human-in-the-Loop: Critical operations require user approval via draft system

Tool Categories

Priority Tiers

Tools are organized into priority tiers based on usage frequency:

Tier	Usage	Tool Count	Examples
P0 Critical	50-80% of conversations	4 tools	`fetch_and_display`, `prepare_spreadsheet_workspace`
P1 High Priority	30-40% of conversations	7 tools	`nl_query`, `create_spreadsheet_chart`, `emit_agent_insight`
P2 Feature	10-30% of conversations	15 tools	`generate_report`, `validate_compliance`, `query_resource_details`
Specialized	5-10% of conversations	107 tools	Domain-specific tools for advanced workflows

P0 Critical Tools (4 Tools)

These tools power the majority of agent interactions. Agents automatically prioritize these in their reasoning.

prepare_spreadsheet_workspace - Set up spreadsheet environment

Purpose: Initialize a Univer Sheets workspace before any spreadsheet operations.When to Use:

User asks to “add data to a spreadsheet”
Before inserting data into sheets
Creating new workbooks

Example:

User: "Create a portfolio holdings spreadsheet"

Agent: prepare_spreadsheet_workspace(
    purpose="portfolio holdings analysis",
    suggestedWorkbookName="Portfolio Holdings Q4 2025"
)

Returns: UI action to create workbook, navigate to it, and select cell A1.

fetch_and_display - Universal data retrieval and display

Purpose: Fetch data from database and display in appropriate UI (spreadsheet, document, slide, widget).When to Use:

User wants to see database data in any UI component
“Show me portfolios”, “Add holdings to sheet”, “Create dashboard”

Example:

User: "Show me active portfolios"

Agent: fetch_and_display(
    query="SELECT * FROM investment.portfolios WHERE portfolio_status = 'Active'",
    explanation="Fetching active portfolios for display",
    uiTarget="auto"  # Auto-detects current UI context
)

Supported UI Targets:

spreadsheet - Univer Sheets (Excel-like grids)
document - Univer Docs (rich text documents)
slide - Univer Slides (presentations)
widget - Dashboard widgets
dashboard - Full dashboard layouts
formula - Formula builder interface
auto - Automatic detection based on workspace context

Returns: Formatted data with appropriate UI action for insertion.

fetch_and_insert_to_spreadsheet - Atomic spreadsheet data insertion

Purpose: Fetch data and insert into spreadsheet in ONE atomic operation.When to Use:

User explicitly wants data in a spreadsheet
Reliability is critical (one-step operation reduces failure points)

Example:

User: "Put transaction data in the sheet"

Agent: fetch_and_insert_to_spreadsheet(
    query="SELECT * FROM investment.transactions WHERE transaction_date >= CURRENT_DATE - 30",
    explanation="Last 30 days of transactions",
    includeHeaders=True,
    startRow=0,
    startCol=0
)

Returns: Row count and UI action to insert data at specified location.

insert_data_to_spreadsheet - Insert pre-fetched data

Purpose: Insert already-fetched data array into spreadsheet.When to Use:

You already have data from another tool call
Inserting transformed or filtered data

Example:

# Step 1: Get data from database tool
result = execute_database_query(...)

# Step 2: Insert the data
Agent: insert_data_to_spreadsheet(
    data=result.data,  # MUST pass the data array
    startRow=0,
    includeHeaders=True
)

Common Mistake: Forgetting to pass the data parameter. Always pass the data array from previous query results.

Returns: UI action with row/column count for insertion.

P1 High Priority Tools (7 Tools)

Data Access & Querying

nl_query - Natural language to SQL (PRIMARY data access)

Purpose: Convert plain English questions to validated SQL queries and return formatted results.This is the PRIMARY tool for accessing database information. Use this for all user questions about data.Capabilities:

Converts natural language to SQL using GPT-4 with full schema context
Validates SQL for safety (blocks DROP, DELETE, etc.)
Executes query with row limits
Formats results in natural language
Stores query history for learning

Context-Aware Features:

Auto-filters by selected portfolio/date if available
Focuses on relevant tables from current page context
Uses active dashboard/workflow state to scope queries

Example:

User: "Which portfolios have the highest VaR this month?"

Agent: nl_query(
    question="Which portfolios have the highest VaR this month?",
    include_sql=True,
    max_results=100
)

# Returns:
{
    "success": True,
    "summary": "Found 12 portfolios with VaR data. Top 3: ABC Fund (VaR: $2.3M), XYZ Fund (VaR: $1.8M)...",
    "data": [...],
    "sql_query": "SELECT portfolio_name, var_95 FROM risk.portfolio_risk_metrics...",
    "generation": {
        "confidence": 0.95,
        "explanation": "Queried risk.portfolio_risk_metrics for VaR calculations",
        "tables_used": ["risk.portfolio_risk_metrics", "investment.portfolios"]
    }
}

Best Practices:

Use for ALL data retrieval questions
Let the tool handle SQL generation (don’t write SQL manually)
Check confidence score - warn user if < 0.7
Review warnings array for potential issues

get_query_history - Learn from past queries

Purpose: Retrieve recent successful queries to improve future query generation.When to Use:

Understanding common query patterns
Finding examples for similar questions
Debugging failed queries

Example:

result = get_query_history(limit=20, user_id="user-123")

# Returns:
{
    "success": True,
    "total_queries": 20,
    "successful_count": 18,
    "failed_count": 2,
    "common_patterns": [
        {
            "pattern": "Aggregation",
            "count": 8,
            "examples": [...]
        }
    ],
    "suggestions": [
        "Try: 'Show me all active portfolios ordered by AUM'",
        "Try: 'What validation rules failed today?'"
    ]
}

Visualization & Analysis

create_spreadsheet_chart - Visualize data in sheets

Purpose: Create charts and visualizations within Univer Sheets.Chart Types:

line - Time series, trends
bar - Comparisons, rankings
pie - Composition, percentages
scatter - Correlations, distributions
area - Cumulative values

Example:

User: "Show portfolio AUM over time as a line chart"

Agent: create_spreadsheet_chart(
    chartType="line",
    dataRange="A1:B13",
    title="Portfolio AUM Trend",
    xAxisLabel="Date",
    yAxisLabel="AUM ($M)"
)

create_pivot_table - Aggregate and summarize

Purpose: Create pivot tables for data aggregation and analysis.Example:

Agent: create_pivot_table(
    dataRange="A1:E100",
    rowFields=["portfolio_name"],
    columnFields=["asset_class"],
    valueField="market_value",
    aggregation="sum"
)

spreadsheet_analyze - AI-powered data analysis

Purpose: Use AI to analyze data patterns, outliers, and insights in spreadsheets.Example:

Agent: spreadsheet_analyze(
    dataRange="A1:F100",
    analysisType="outlier_detection",
    context="Looking for unusual holdings concentrations"
)

Communication & Insights

emit_agent_insight - Proactive recommendations

Purpose: Send proactive insights and recommendations to the user.Insight Categories:

info - Informational messages
warning - Potential issues requiring attention
risk - Risk alerts and compliance concerns
dependency - Workflow dependencies and blockers

Example:

Agent: emit_agent_insight(
    message="Portfolio ABC has 3 validation breaches requiring immediate review",
    category="warning",
    references=["validation-breach-001", "validation-breach-002"]
)

When to Use:

Discovered issues during analysis
Proactive risk identification
Workflow status updates
Dependency alerts

record_agent_draft - Propose changes for approval

Purpose: Record proposed changes for user review before execution (Human-in-the-Loop).Example:

Agent: record_agent_draft(
    agentId="fund-accountant",
    title="Auto-reconcile 5 NAV breaks",
    summary="Identified root causes for 5 NAV variances. Propose automatic resolution.",
    payload={
        "reconciliations": [...]
    },
    metadata={
        "rationale": "All breaks are due to timing differences in custodian feeds",
        "risks": ["Automatic adjustment may mask underlying data quality issues"],
        "nextActions": ["Validate custodian feed timing", "Update reconciliation rules"]
    }
)

Always use drafts for:

Data modifications
Compliance approvals
Workflow changes
High-risk operations

apply_agent_draft - Execute approved changes

Purpose: Apply a draft that has been approved by the user.Example:

# After user approves draft
Agent: apply_agent_draft(
    draftId="draft-12345",
    userId="user-789"
)

Spreadsheet Automation (6 Tools)

These tools provide Excel-equivalent functionality for Univer Sheets, the platform’s spreadsheet engine.

Spreadsheet Manipulation Tools

spreadsheet_set_cell

Set a single cell value (text, number, boolean).

spreadsheet_set_cell(row=0, col=0, value="Portfolio Name")

spreadsheet_get_cell

Read a cell’s value, formula, and formatting.

spreadsheet_get_cell(row=5, col=3)

spreadsheet_set_formula

Create calculated cells with Excel-style formulas.Supported Functions:

Math: SUM(), AVERAGE(), MIN(), MAX(), ROUND()
Logic: IF(), AND(), OR(), NOT()
Text: CONCATENATE(), LEFT(), RIGHT()

spreadsheet_set_formula(row=10, col=5, formula="=SUM(A1:A10)")

spreadsheet_select_range

Highlight a range of cells for user attention.

spreadsheet_select_range(
    startRow=0, startCol=0,
    endRow=10, endCol=5
)

spreadsheet_insert_row

Insert one or more blank rows.

spreadsheet_insert_row(rowIndex=5, count=3)

select_spreadsheet_cell

Select a specific cell to direct user focus.

select_spreadsheet_cell(
    row=0, col=0,
    reason="Enter portfolio name here"
)

Database Operations (5 Tools)

Database Query & Schema Tools

execute_database_query

Execute SQL queries with automatic tenant isolation.

execute_database_query(
    query="SELECT * FROM investment.portfolios WHERE portfolio_status = 'Active'",
    schema="investment"
)

Prefer nl_query over this tool. Use execute_database_query only when you need direct SQL control for complex queries.

get_schema_info

Retrieve database schema metadata (tables, columns, relationships).

get_schema_info(schema="investment")

# Returns table list, column definitions, foreign keys

get_table_summary

Get table statistics (row counts, column types, sample data).

get_table_summary(
    schema="investment",
    table="portfolios"
)

query_resource_details

Fetch detailed information about a specific resource (portfolio, fund, security).

query_resource_details(
    resourceType="portfolio",
    resourceId="portfolio-uuid-123"
)

get_database_catalog

List all accessible schemas and tables for current user.

get_database_catalog()

# Returns: {
#   "investment": ["portfolios", "holdings", "securities"],
#   "validation": ["rules", "validation_results"],
#   ...
# }

Natural Language Query (2 Tools)

Already covered in P1 High Priority Tools:

nl_query - Convert natural language to SQL
get_query_history - Learn from past queries

Breach & Anomaly Detection (4 Tools)

Predictive Analytics & Alerts

predict_breach

ML-powered prediction of future compliance breaches.

predict_breach(
    portfolioId="portfolio-123",
    rule="NAV_VARIANCE_3BP",
    lookAheadDays=7
)

# Returns:
{
    "breach_probability": 0.78,
    "confidence": 0.85,
    "risk_factors": ["Historical volatility", "Market conditions"],
    "recommended_actions": ["Increase monitoring frequency", "Review tolerance settings"]
}

get_breach_risk_score

Calculate aggregate risk score for all portfolios.

get_breach_risk_score(portfolioIds=["p1", "p2", "p3"])

detect_anomaly

Real-time outlier detection in holdings and transactions.

detect_anomaly(
    dataType="holdings",
    portfolioId="portfolio-123",
    sensitivity=0.8  # 0.0-1.0
)

# Returns outliers with explanations

get_anomaly_alerts

Retrieve active anomaly alerts for monitoring.

get_anomaly_alerts(
    portfolioId="portfolio-123",
    status="active"
)

Reconciliation (2 Tools)

Automated Break Analysis

auto_reconcile

Automatically analyze and resolve NAV breaks.

auto_reconcile(
    portfolioId="portfolio-123",
    date="2025-10-29",
    toleranceBps=3  # 3 basis points
)

# Returns:
{
    "total_breaks": 5,
    "auto_resolved": 3,
    "manual_review_required": 2,
    "resolutions": [
        {
            "break_id": "break-001",
            "root_cause": "Timing difference in custodian feed",
            "proposed_adjustment": 150.25,
            "confidence": 0.92
        }
    ]
}

get_reconciliation_history

Retrieve reconciliation audit trail.

get_reconciliation_history(
    portfolioId="portfolio-123",
    dateRange={"start": "2025-10-01", "end": "2025-10-29"}
)

Compliance & Governance (6 Tools)

ASIC RG94 Compliance Tools

check_compliance

Validate action against regulatory requirements (SOX, ASIC RG94, AIFMD).

check_compliance(
    action_type="validation",
    action_data={
        "portfolio_id": "portfolio-123",
        "nav_variance": 0.05  # 5 basis points
    }
)

# Returns:
{
    "passed": False,
    "violations": [
        {
            "rule": "ASIC_RG94_NAV_TOLERANCE",
            "threshold": 0.03,  # 3bp
            "actual": 0.05,     # 5bp
            "severity": "high"
        }
    ]
}

request_approval

Initiate approval workflow for compliance-sensitive actions.

request_approval(
    action_type="transaction_reversal",
    action_data={...},
    requested_by="user-123",
    reason="Erroneous trade entry detected"
)

submit_approval_decision

Approve or reject a pending approval request.

submit_approval_decision(
    request_id="approval-456",
    approver_id="user-789",
    approved=True,
    comments="Reviewed and approved - legitimate correction"
)

get_pending_approvals

Retrieve approvals awaiting decision.

get_pending_approvals(approverId="user-789")

generate_compliance_report

Generate regulatory compliance reports.Report Types:

sox_audit - Sarbanes-Oxley audit trail
rg94_validation - ASIC RG94 validation summary
aifmd - AIFMD valuation compliance
agent_activity - AI agent action audit
approval_workflow - Approval workflow report

generate_compliance_report(
    report_type="rg94_validation",
    period_days=30
)

verify_audit_integrity

Verify completeness and integrity of audit logs.

verify_audit_integrity(
    startDate="2025-10-01",
    endDate="2025-10-29"
)

Report Generation (3 Tools)

Automated Reporting

generate_report

Generate regulatory and operational reports.Report Types:

nav_certification - Daily NAV certification
breach_summary - Validation breach report
reconciliation_status - Reconciliation summary
performance_attribution - Performance analysis
compliance_summary - Compliance status

generate_report(
    report_type="nav_certification",
    portfolioId="portfolio-123",
    date="2025-10-29",
    format="pdf"
)

list_report_templates

Browse available report templates.

list_report_templates(category="compliance")

schedule_report

Schedule recurring report generation.

schedule_report(
    report_type="breach_summary",
    frequency="daily",
    time="08:00",
    recipients=["[email protected]"]
)

Workflow Generation (3 Tools)

Temporal Workflow Automation

generate_workflow

Generate Temporal workflow definitions from natural language.

generate_workflow(
    description="Daily NAV validation with automatic reconciliation and email notifications",
    trigger="cron",
    triggerConfig={"schedule": "0 8 * * *"}  # 8 AM daily
)

# Returns Temporal workflow YAML definition

validate_workflow

Validate workflow definition before deployment.

validate_workflow(
    workflow_definition={...}
)

optimize_workflow

Suggest workflow optimizations.

optimize_workflow(
    workflow_id="workflow-789"
)

# Returns:
{
    "suggestions": [
        "Parallelize custodian data fetches (20% faster)",
        "Cache validation rules (reduce DB queries by 50%)"
    ]
}

Scheduling Optimization (3 Tools)

Task Scheduling & Optimization

optimize_schedule

Optimize task scheduling to minimize bottlenecks.

optimize_schedule(
    tasks=[
        {"id": "fetch_prices", "duration": 300, "dependencies": []},
        {"id": "calc_nav", "duration": 120, "dependencies": ["fetch_prices"]},
        {"id": "validate", "duration": 60, "dependencies": ["calc_nav"]}
    ]
)

# Returns optimized schedule with start times

analyze_schedule_patterns

Analyze historical scheduling patterns for bottlenecks.

analyze_schedule_patterns(
    workflow_id="daily-nav-workflow",
    period_days=30
)

get_scheduling_statistics

Retrieve scheduling performance metrics.

get_scheduling_statistics(workflow_id="daily-nav-workflow")

Smart Suggestions (5 Tools)

Context-Aware Automation Suggestions

generate_suggestions

Generate context-aware automation suggestions.

generate_suggestions(
    context="User reviewing NAV breaks",
    limit=3
)

# Returns:
[
    {
        "title": "Auto-reconcile timing differences",
        "action": "auto_reconcile",
        "confidence": 0.87,
        "reason": "3 breaks have same root cause pattern"
    }
]

apply_suggestion

Apply a suggestion with one click.

apply_suggestion(suggestion_id="sugg-123")

undo_suggestion

Rollback a previously applied suggestion.

undo_suggestion(suggestion_id="sugg-123")

provide_suggestion_feedback

Improve suggestions through feedback.

provide_suggestion_feedback(
    suggestion_id="sugg-123",
    helpful=True,
    comment="Saved 30 minutes of manual work"
)

get_suggestion_stats

Retrieve suggestion performance metrics.

get_suggestion_stats(userId="user-123")

Agent Delegation (3 Tools)

Multi-Agent Collaboration

delegate_to_agent

Delegate task to a specialized agent.

delegate_to_agent(
    target_agent="compliance-sentinel",
    task="Validate all portfolios against ASIC RG94 requirements",
    context={
        "portfolios": ["p1", "p2", "p3"],
        "date": "2025-10-29"
    }
)

execute_parallel_tasks

Execute tasks across multiple agents in parallel.

execute_parallel_tasks(
    tasks=[
        {"agent": "data-quality-analyst", "task": "Profile data quality"},
        {"agent": "compliance-sentinel", "task": "Check compliance"},
        {"agent": "risk-analyst", "task": "Calculate VaR"}
    ]
)

get_delegation_history

Retrieve agent delegation audit trail.

get_delegation_history(sessionId="session-123")

Memory & Context (4 Tools)

Agent Memory & Learning

remember_fact

Store facts for future recall.

remember_fact(
    fact="User prefers NAV reports in PDF format",
    category="user_preference",
    importance=0.8
)

recall_cases

Retrieve similar past cases for context.

recall_cases(
    query="NAV break due to FX rate mismatch",
    limit=5
)

learn_from_feedback

Update knowledge base from user corrections.

learn_from_feedback(
    original_action="auto_reconcile",
    feedback="Should have flagged for manual review",
    outcome="negative"
)

get_memory_statistics

Retrieve memory system statistics.

get_memory_statistics(userId="user-123")

Document Extraction (2 Tools)

Intelligent Document Processing

extract_from_document

Extract structured data from PDFs and text documents.

extract_from_document(
    document_url="https://storage/custodian-report.pdf",
    extraction_type="holdings",
    schema={
        "fields": ["security_name", "quantity", "market_value", "currency"]
    }
)

# Returns structured data array

get_extraction_history

Retrieve document extraction history.

get_extraction_history(limit=20)

Explainability & HITL (3 Tools)

Transparent AI Decisions

explain_decision

Explain why the agent made a specific decision.

explain_decision(
    decision_id="decision-456",
    detail_level="detailed"  # "summary" | "detailed" | "technical"
)

# Returns:
{
    "reasoning": "Identified 5 NAV breaks with same root cause pattern...",
    "evidence": [
        "Break-001: Timing difference of +2 hours",
        "Break-002: Timing difference of +2.5 hours"
    ],
    "confidence": 0.92,
    "alternative_actions": [
        "Manual review of all breaks",
        "Adjust custodian feed timing"
    ]
}

provide_feedback

Provide feedback on agent actions.

provide_feedback(
    action_id="action-789",
    rating=5,  # 1-5
    comment="Accurate and saved significant time"
)

get_explainability_stats

Retrieve explanation statistics.

get_explainability_stats(agentId="fund-accountant")

Self-Healing Workflows (2 Tools)

Automatic Error Recovery

auto_heal_workflow

Automatically recover from workflow errors.

auto_heal_workflow(
    workflow_id="daily-nav-workflow",
    error_type="connection_timeout"
)

# Returns healing actions taken (retry, fallback, skip, etc.)

get_healing_history

Retrieve self-healing audit trail.

get_healing_history(
    workflow_id="daily-nav-workflow",
    period_days=7
)

Analytics & Performance (4 Tools)

Cross-Agent Performance Analytics

get_agent_analytics

Retrieve performance analytics for agents.

get_agent_analytics(
    agentId="fund-accountant",
    metrics=["accuracy", "response_time", "user_satisfaction"]
)

get_performance_trends

Analyze agent performance trends over time.

get_performance_trends(
    agentId="fund-accountant",
    period_days=30
)

calculate_roi

Calculate ROI of agent automation.

calculate_roi(
    workflow="nav-validation",
    period_days=30
)

# Returns:
{
    "time_saved_hours": 120,
    "error_reduction_percent": 95,
    "cost_savings": "$15,000"
}

compare_agents

Compare performance across multiple agents.

compare_agents(
    agentIds=["fund-accountant", "compliance-sentinel"],
    metrics=["accuracy", "speed"]
)

Dashboard Control (8 Tools)

Dashboard Builder Automation

create_dashboard

Create new dashboard from template or scratch.

create_dashboard(
    name="Portfolio Risk Dashboard",
    template_id="risk-overview",
    description="Real-time portfolio risk monitoring"
)

Add widget to dashboard.

add_widget(
    dashboard_id="dash-123",
    widget_type="chart",
    title="VaR by Portfolio",
    config={
        "chartType": "bar",
        "dataSource": "risk.portfolio_risk_metrics",
        "xField": "portfolio_name",
        "yField": "var_95"
    }
)

Update existing widget configuration.

configure_widget(
    dashboard_id="dash-123",
    widget_id="widget-456",
    config={"colors": ["#FF6B6B", "#4ECDC4"]}
)

Remove widget from dashboard.

remove_widget(dashboard_id="dash-123", widget_id="widget-456")

apply_dashboard_filter

Apply global filters to dashboard.

apply_dashboard_filter(
    dashboard_id="dash-123",
    filters=[
        {"field": "portfolio_id", "operator": "in", "value": ["p1", "p2"]},
        {"field": "date", "operator": ">=", "value": "2025-10-01"}
    ]
)

export_dashboard

Export dashboard to PDF, PNG, JSON, or Excel.

export_dashboard(
    dashboard_id="dash-123",
    format="pdf",
    options={"pageSize": "A4", "quality": "high"}
)

submit_dashboard_for_approval

Submit dashboard for compliance approval.

submit_dashboard_for_approval(
    dashboard_id="dash-123",
    approvers=["user-789"],
    comment="New risk dashboard for board review"
)

get_dashboard_details

Retrieve dashboard configuration and widgets.

get_dashboard_details(
    dashboard_id="dash-123",
    include_widgets=True
)

Data Modeler Control (9 Tools)

Visual Query Builder Automation

add_table_to_canvas

Add table to visual query builder canvas.

add_table_to_canvas(
    schema="investment",
    table="portfolios",
    position={"x": 100, "y": 100}
)

create_join

Create join between tables.

create_join(
    leftTable="investment.portfolios",
    rightTable="investment.holdings",
    joinType="inner",
    condition="portfolios.portfolio_id = holdings.portfolio_id"
)

add_filter

Add filter to query.

add_filter(
    field="portfolio_status",
    operator="equals",
    value="Active"
)

add_calculation

Add calculated field.

add_calculation(
    name="total_value",
    formula="quantity * price",
    dataType="decimal"
)

select_columns

Choose columns to include in query.

select_columns(
    columns=[
        "portfolios.portfolio_name",
        "holdings.security_name",
        "holdings.market_value"
    ]
)

generate_sql

Generate SQL from visual query.

generate_sql()

# Returns optimized SQL with proper joins and filters

preview_query_results

Preview query results before execution.

preview_query_results(limit=10)

save_query

Save query for reuse.

save_query(
    name="Active Portfolio Holdings",
    description="Holdings for all active portfolios",
    category="portfolio_analysis"
)

export_query_results

Export query results to various formats.

export_query_results(
    format="excel",
    filename="holdings_export.xlsx"
)

Complete Frontend Automation

navigate_to_page

Navigate to specific page/view.

navigate_to_page(
    page="/data-modeling",
    params={"workbookId": "wb-123"}
)

Open modal dialog.

open_modal(
    modalType="create_portfolio",
    props={"defaultValues": {...}}
)

Close active modal.

close_modal()

click_button

Trigger button click.

click_button(buttonId="save-portfolio-btn")

fill_form_field

Populate form field.

fill_form_field(
    fieldId="portfolio_name",
    value="Global Equity Fund"
)

submit_form

Submit form.

submit_form(formId="create-portfolio-form")

select_tab

Switch to specific tab.

select_tab(tabId="holdings-tab")

Show/hide sidebar.

toggle_sidebar(visible=False)

show_notification

Display toast notification.

show_notification(
    message="Portfolio created successfully",
    type="success",
    duration=3000
)

scroll_to_element

Scroll to specific element.

scroll_to_element(elementId="validation-breach-section")

highlight_element

Highlight element for user attention.

highlight_element(
    elementId="nav-variance-cell",
    duration=2000
)

Open context menu.

open_context_menu(
    targetId="portfolio-row-5",
    position={"x": 300, "y": 200}
)

trigger_keyboard_shortcut

Simulate keyboard shortcut.

trigger_keyboard_shortcut(
    shortcut="ctrl+s"  # Save
)

update_url_params

Update URL parameters without navigation.

update_url_params(
    params={"portfolioId": "p-123", "date": "2025-10-29"}
)

ETL Control (13 Tools)

Data Pipeline Automation

create_pipeline

Create new data pipeline.

create_pipeline(
    name="Custodian Daily Feed",
    source="sftp://custodian.com/daily",
    destination="investment.holdings"
)

configure_source

Configure data source.

configure_source(
    pipeline_id="pipe-123",
    source_type="sftp",
    config={
        "host": "custodian.com",
        "username": "user",
        "path": "/daily/*.csv"
    }
)

map_fields

Map source fields to destination schema.

map_fields(
    pipeline_id="pipe-123",
    mappings=[
        {"source": "ISIN", "destination": "security_isin"},
        {"source": "QTY", "destination": "quantity"}
    ]
)

add_transformation

Add data transformation rule.

add_transformation(
    pipeline_id="pipe-123",
    transformation_type="ai_normalize",
    config={
        "field": "security_name",
        "rules": ["Remove extra whitespace", "Standardize case"]
    }
)

add_validation_rule

Add data quality validation.

add_validation_rule(
    pipeline_id="pipe-123",
    rule_type="not_null",
    field="security_isin"
)

add_data_quality_check

Add data quality check.

add_data_quality_check(
    pipeline_id="pipe-123",
    check_type="duplicate_detection",
    field="security_isin"
)

configure_schedule

Schedule pipeline execution.

configure_schedule(
    pipeline_id="pipe-123",
    schedule="0 8 * * *",  # Daily at 8 AM
    timezone="America/New_York"
)

run_pipeline

Execute pipeline immediately.

run_pipeline(pipeline_id="pipe-123")

get_pipeline_status

Check pipeline execution status.

get_pipeline_status(pipeline_id="pipe-123")

get_pipeline_logs

Retrieve pipeline execution logs.

get_pipeline_logs(
    pipeline_id="pipe-123",
    limit=50
)

view_data_lineage

View data lineage graph.

view_data_lineage(
    table="investment.holdings",
    upstream=True,
    downstream=True
)

export_pipeline_config

Export pipeline configuration.

export_pipeline_config(
    pipeline_id="pipe-123",
    format="json"
)

clone_pipeline

Duplicate existing pipeline.

clone_pipeline(
    source_pipeline_id="pipe-123",
    new_name="Custodian Daily Feed - Backup"
)

Valuation Tools (5 Tools)

Private Equity Valuation Suite

calculate_dcf_valuation

Perform Discounted Cash Flow valuation.

calculate_dcf_valuation(
    revenue=[100, 110, 121, 133, 146],  # 5-year projections
    revenue_growth_rate=10.0,
    ebitda_margin=25.0,
    tax_rate=21.0,
    capex_as_percent_of_revenue=5.0,
    nwc_as_percent_of_revenue=10.0,
    wacc=10.0,
    terminal_growth_rate=3.0,
    net_debt=50.0
)

# Returns:
{
    "enterprise_value": 825.5,
    "equity_value": 775.5,
    "implied_ev_ebitda_multiple": 11.2,
    "free_cash_flows": [18.5, 20.4, 22.4, 24.6, 27.1],
    "terminal_value": 387.1,
    "present_value_fcf": 438.4,
    "present_value_terminal": 387.1
}

calculate_comparable_companies

Calculate valuation based on comparable companies.

calculate_comparable_companies(
    target_revenue=100.0,
    target_ebitda=25.0,
    comparables=[
        {"company": "Comp A", "ev_revenue": 2.5, "ev_ebitda": 12.0},
        {"company": "Comp B", "ev_revenue": 3.0, "ev_ebitda": 14.0}
    ]
)

validate_valuation_assumptions

Validate reasonableness of valuation assumptions.

validate_valuation_assumptions(
    assumptions={
        "revenue_growth_rate": 50.0,  # High growth
        "ebitda_margin": 60.0,        # Very high margin
        "wacc": 5.0                   # Low discount rate
    },
    industry="software"
)

# Returns validation warnings and benchmarks

generate_investment_memo

Generate investment memo document.

generate_investment_memo(
    company_name="Tech Startup Inc",
    valuation_results={...},
    investment_thesis="Leading position in AI infrastructure",
    risks=["Regulatory changes", "Competition"],
    template="standard"
)

generate_investment_recommendation

Generate investment recommendation based on analysis.

generate_investment_recommendation(
    valuation_results={...},
    target_return=25.0,
    risk_tolerance="moderate"
)

# Returns: "buy", "hold", or "pass" with rationale

Spectacle Visualization (5 Tools)

Spectacle Chart & Dashboard Creation

create_spectacle_chart

Create chart using Spectacle library.

create_spectacle_chart(
    chartType="line",
    data=[...],
    title="Portfolio Performance",
    xAxis="date",
    yAxis="value"
)

create_spectacle_dashboard

Create dashboard with Spectacle.

create_spectacle_dashboard(
    name="Executive Dashboard",
    layout="grid",
    widgets=[...]
)

Add widget to Spectacle dashboard.

add_spectacle_widget(
    dashboard_id="dash-123",
    widget_type="metric",
    config={...}
)

create_spectacle_slide

Create presentation slide with Spectacle.

create_spectacle_slide(
    presentation_id="pres-123",
    layout="title_and_content",
    content={...}
)

export_spectacle_visualization

Export Spectacle visualization.

export_spectacle_visualization(
    viz_id="viz-123",
    format="png",
    options={"resolution": "high"}
)

Lexical Document Editor (6 Tools)

Rich Text Document Creation

create_lexical_document

Create new Lexical document.

create_lexical_document(
    title="Investment Memo - Tech Startup Inc",
    template="investment_memo"
)

insert_text

Insert text at cursor position.

insert_text(
    document_id="doc-123",
    text="This is the executive summary...",
    position="end"
)

insert_table

Insert table into document.

insert_table(
    document_id="doc-123",
    rows=5,
    columns=3,
    headers=["Metric", "2024", "2025"]
)

insert_heading

Insert heading.

insert_heading(
    document_id="doc-123",
    text="Financial Projections",
    level=2  # H2
)

insert_list

Insert bulleted or numbered list.

insert_list(
    document_id="doc-123",
    items=["Risk 1", "Risk 2", "Risk 3"],
    list_type="bullet"
)

format_text

Apply formatting to selected text.

format_text(
    document_id="doc-123",
    selection={"start": 0, "end": 20},
    formatting={"bold": True, "fontSize": 18}
)

Multi-Option Tools (3 Tools)

Multiple Solution Generation

generate_options

Generate multiple solution options for user choice.

generate_options(
    problem="How to resolve 5 NAV breaks?",
    num_options=3
)

# Returns 3 different approaches with pros/cons

refine_option

Refine a specific option based on user feedback.

refine_option(
    option_id="opt-123",
    feedback="Focus more on automation"
)

compare_options

Compare multiple options side-by-side.

compare_options(
    option_ids=["opt-123", "opt-456"],
    criteria=["time", "accuracy", "automation_level"]
)

Tool Selection Guide

When to Use Which Tool?

User Asks a Question

Primary Tool: nl_queryConvert natural language to SQL and return formatted results.Example: “Which portfolios are underperforming?”

User Wants Data in Spreadsheet

Primary Tool: fetch_and_display or fetch_and_insert_to_spreadsheetAtomic operation to fetch and insert data.Example: “Add holdings to the sheet”

User Requests a Report

Primary Tool: generate_reportGenerate formatted reports with templates.Example: “Generate NAV certification report”

User Wants to Create a Dashboard

Primary Tool: create_dashboard + add_widgetBuild custom dashboards programmatically.Example: “Create a risk monitoring dashboard”

User Needs Compliance Check

Primary Tool: check_complianceValidate against regulatory requirements.Example: “Is this NAV variance compliant?”

User Asks for Automation

Primary Tool: generate_workflow + generate_suggestionsCreate workflows and suggest automations.Example: “Automate daily NAV validation”

Decision Tree

Tool Security & Permissions

Tenant Isolation

Every tool execution is wrapped with tenant context injection:

@with_tenant_context
async def tool_function(*args, **kwargs):
    # Tenant ID automatically injected
    # All queries scoped to user's organization
    tenant_id = kwargs["tenant_id"]
    ...

Benefits:

Data Isolation: Users only see their organization’s data
Audit Trail: Every tool call logged with tenant context
Quota Enforcement: Rate limits per tenant
Permission Checks: IAM-based access control

Row-Level Security (RLS)

Database queries automatically filtered by RLS policies:

-- Example: Users can only access portfolios in their team
CREATE POLICY "Users access team portfolios"
ON investment.portfolios
FOR SELECT
USING (
    portfolio_id IN (
        SELECT portfolio_id
        FROM iam.team_members
        WHERE user_id = auth.uid()
    )
);

Protected Schemas:

✅ iam.* - Identity and access management
✅ vault.* - Credential storage (admin-only)
✅ agent.* - Agent sessions and drafts
✅ investment.* - Portfolio and holdings data
✅ validation.* - Compliance validation data
✅ audit.* - Audit logs (compliance/admin only)

Permission Model

IAM Roles:

ADMIN - Full system access (GLOBAL scope)
FUND_MANAGER - Manage funds and strategies (ORGANIZATION scope)
PORTFOLIO_MANAGER - Manage portfolios (TEAM scope)
OPERATIONS_LEAD - Operational activities (ORGANIZATION scope)
COMPLIANCE_OFFICER - Compliance and audits (ORGANIZATION scope)
VIEWER - Read-only access (TEAM scope)

Tool Permissions by Role:

Tool Category	Viewer	Portfolio Manager	Operations Lead	Compliance Officer	Admin
Data Query	✅ Read	✅ Read	✅ Read	✅ Read	✅ Full
Spreadsheet	✅ Read	✅ Full	✅ Full	✅ Read	✅ Full
Reports	✅ Read	✅ Generate	✅ Generate	✅ Full	✅ Full
Compliance	❌	❌	✅ Check	✅ Full	✅ Full
Workflows	❌	❌	✅ Full	✅ Read	✅ Full
Approvals	❌	✅ Request	✅ Approve	✅ Approve	✅ Full
Admin Tools	❌	❌	❌	❌	✅ Full

Destructive Operations Require Approval:

Data modifications (UPDATE, DELETE)
Compliance approvals
Workflow changes
Always use the draft system for high-risk operations

Tool Execution Flow

Standard Execution

Human-in-the-Loop Execution

Error Handling

Tool Performance Characteristics

Latency Benchmarks

Tool Category	P50 Latency	P95 Latency	Notes
nl_query	2.5s	5.0s	Includes GPT-4 reasoning + SQL execution
Database Query	150ms	500ms	Direct SQL, no AI
Spreadsheet	50ms	200ms	Client-side execution
Dashboard	300ms	1.0s	Multiple widget queries
Report Generation	5.0s	15.0s	Includes PDF rendering
Workflow Generation	3.0s	8.0s	AI workflow definition generation
Compliance Check	200ms	600ms	Rule evaluation

Optimization Tips

For Faster Data Access:

Use nl_query for complex questions (caches schema)
Use execute_database_query for repeated queries (skip AI reasoning)
Specify max_results to limit data transfer
Use workspace context filters to scope queries

For Reliable Operations:

Use P0 tools (fetch_and_display, prepare_spreadsheet_workspace) for common tasks
Always use drafts for high-risk operations
Check tool return status before proceeding
Provide clear error messages to users

Creating Custom Tools

Developers can extend the agent system with custom tools. See Advanced: Custom Tool Development for details.

Tool Template

from langchain_core.tools import tool
from pydantic import BaseModel, Field
from typing import Optional

class MyToolInput(BaseModel):
    """Input schema for my custom tool"""
    param1: str = Field(description="Parameter description")
    param2: int = Field(default=10, description="Optional parameter")

@tool("my_custom_tool", args_schema=MyToolInput)
def my_custom_tool(
    param1: str,
    param2: int = 10,
    config: Optional[RunnableConfig] = None
) -> dict:
    """
    Brief description of what this tool does.

    Detailed description with use cases and examples.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Result dictionary with success status and data
    """
    try:
        # Tool implementation
        result = do_something(param1, param2)

        return {
            "success": True,
            "data": result
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }

Registering Custom Tools

# In app/agent/tools/__init__.py
from app.agent.tools.my_custom_tools import get_my_tools

def get_all_tools(agent_id: Optional[str] = None):
    tools = [
        # ... existing tools
    ]

    # Add custom tools
    tools.extend(get_my_tools())

    return tools

Summary

Tool Statistics

Total Tools: 133 tools
P0 Critical: 4 tools (50-80% usage)
P1 High Priority: 7 tools (30-40% usage)
P2 Feature: 15 tools (10-30% usage)
Specialized: 107 tools (5-10% usage)

Coverage Areas

Data Access

Natural language query
Direct SQL execution
Schema inspection
Resource details

Automation

Spreadsheet manipulation
Dashboard creation
Workflow generation
Report automation

Intelligence

Breach prediction
Anomaly detection
Auto-reconciliation
Smart suggestions

Governance

Compliance checks
Approval workflows
Audit trails
ASIC RG94 validation

Collaboration

Agent delegation
Multi-agent coordination
Draft system
User feedback

Insights

Explainable AI
Memory & learning
Performance analytics
ROI calculation

Next Steps

Agent Profiles

Learn about the 10 specialized agents and their capabilities

Integration Patterns

Understand how agents integrate with the frontend

Custom Tool Development

Build your own tools to extend agent capabilities

Security & Compliance

Deep dive into tool security and compliance features

Have Questions?

API Documentation: See /docs/api/agent-api.yaml for OpenAPI specs
Developer Guide: See opshub-agent-backend/README.md
Support: Contact [email protected]

Agent System Overview

Available Agents

Integration Patterns

Agent Tools & Capabilities

​Agent Tools & Capabilities

​Introduction

​Tool Execution Model

​Tool Categories

​Priority Tiers

​P0 Critical Tools (4 Tools)

​P1 High Priority Tools (7 Tools)

​Data Access & Querying

​Visualization & Analysis

​Communication & Insights

​Spreadsheet Automation (6 Tools)

​spreadsheet_set_cell

​spreadsheet_get_cell

​spreadsheet_set_formula

​spreadsheet_select_range

​spreadsheet_insert_row

​select_spreadsheet_cell

​Database Operations (5 Tools)

​execute_database_query

​get_schema_info

​get_table_summary

​query_resource_details

​get_database_catalog

​Natural Language Query (2 Tools)

​Breach & Anomaly Detection (4 Tools)

​predict_breach

​get_breach_risk_score

​detect_anomaly

​get_anomaly_alerts

​Reconciliation (2 Tools)

​auto_reconcile

​get_reconciliation_history

​Compliance & Governance (6 Tools)

​check_compliance

​request_approval

​submit_approval_decision

​get_pending_approvals

​generate_compliance_report

​verify_audit_integrity

​Report Generation (3 Tools)

​generate_report

​list_report_templates

​schedule_report

​Workflow Generation (3 Tools)

​generate_workflow

​validate_workflow

​optimize_workflow

​Scheduling Optimization (3 Tools)

​optimize_schedule

​analyze_schedule_patterns

​get_scheduling_statistics

​Smart Suggestions (5 Tools)

​generate_suggestions

​apply_suggestion

​undo_suggestion

​provide_suggestion_feedback

​get_suggestion_stats

​Agent Delegation (3 Tools)

​delegate_to_agent

​execute_parallel_tasks

​get_delegation_history

​Memory & Context (4 Tools)

​remember_fact

​recall_cases

​learn_from_feedback

​get_memory_statistics

​Document Extraction (2 Tools)

​extract_from_document

​get_extraction_history

​Explainability & HITL (3 Tools)

​explain_decision

​provide_feedback

​get_explainability_stats

​Self-Healing Workflows (2 Tools)

​auto_heal_workflow

​get_healing_history

Agent Tools & Capabilities

Introduction

Tool Execution Model

Tool Categories

Priority Tiers

P0 Critical Tools (4 Tools)

P1 High Priority Tools (7 Tools)

Data Access & Querying

Visualization & Analysis

Communication & Insights

Spreadsheet Automation (6 Tools)

spreadsheet_set_cell

spreadsheet_get_cell

spreadsheet_set_formula

spreadsheet_select_range

spreadsheet_insert_row

select_spreadsheet_cell

Database Operations (5 Tools)

execute_database_query

get_schema_info

get_table_summary

query_resource_details

get_database_catalog

Natural Language Query (2 Tools)

Breach & Anomaly Detection (4 Tools)

predict_breach

get_breach_risk_score

detect_anomaly

get_anomaly_alerts

Reconciliation (2 Tools)

auto_reconcile

get_reconciliation_history

Compliance & Governance (6 Tools)

check_compliance

request_approval

submit_approval_decision

get_pending_approvals

generate_compliance_report

verify_audit_integrity

Report Generation (3 Tools)

generate_report

list_report_templates

schedule_report

Workflow Generation (3 Tools)

generate_workflow

validate_workflow

optimize_workflow

Scheduling Optimization (3 Tools)

optimize_schedule

analyze_schedule_patterns

get_scheduling_statistics

Smart Suggestions (5 Tools)

generate_suggestions

apply_suggestion

undo_suggestion

provide_suggestion_feedback

get_suggestion_stats

Agent Delegation (3 Tools)

delegate_to_agent

execute_parallel_tasks

get_delegation_history

Memory & Context (4 Tools)

remember_fact

recall_cases

learn_from_feedback

get_memory_statistics

Document Extraction (2 Tools)

extract_from_document

get_extraction_history

Explainability & HITL (3 Tools)

explain_decision

provide_feedback

get_explainability_stats

Self-Healing Workflows (2 Tools)

auto_heal_workflow

get_healing_history

Analytics & Performance (4 Tools)

get_agent_analytics

get_performance_trends

calculate_roi