Introducing Ontology-Based Tools for OpenPages GRC: A Smarter Way to Work with Your Data

We're excited to announce a powerful new capability in the OpenPages GRC MCP Server: Ontology-Based Tools. This approach brings the benefits of ontology-driven design to AI agents working with OpenPages, making interactions easier, faster, and more intelligent.

What Are Ontology-Based Tools?

While ontology-based approaches are well-established in enterprise software, applying them effectively to AI agent interactions presents unique challenges. Our implementation provides generic, intelligent tools that dynamically adapt to any OpenPages object type through automatic schema discovery—optimized specifically for how Large Language Models understand and process information.

Think of it as the difference between having a separate key for every door in your building versus having a master key that intelligently adapts to any lock. The ontology-based approach gives AI agents a "master key" to your GRC data.

What Makes This Approach Valuable for OpenPages and AI Agents

While ontology-based systems exist in many products, our implementation addresses specific challenges in the AI agent + OpenPages integration space:

What These Tools Provide

1. Universal Object Management

Six powerful generic tools replace dozens of type-specific ones:

Each tool accepts an object_type parameter (e.g., "SOXIssue", "SOXControl", "SOXRisk") and automatically fetches the appropriate schema for validation.

2. Intelligent Schema Caching

The system implements smart caching strategies:

• Compact Mode First: Initial schema reads are 70-90% smaller (only required/system fields)
• Automatic Escalation: Switches to full mode only when needed
• Session-Level Caching: Schemas are read once and reused throughout the session
• Fast Access: Cached schemas accessed in ~1-5ms vs ~100-200ms for fresh reads

3. LLM-Optimized Schema Format

Schemas are published as structured JSON with clear organization that AI agents can parse efficiently:

{
  "type_id": "SOXIssue",
  "display_name": "Issue",
  "namespace": "openpages",
  "path_prefix": "Issue",
  "field_count": 15,
  "fields": [
    {
      "name": "Name",
      "label": "Name",
      "data_type": "STRING_TYPE",
      "description": "Issue name",
      "required": true,
      "read_only": false
    },
    {
      "name": "OPSS-Iss:Status",
      "label": "Status",
      "data_type": "ENUM_TYPE",
      "description": "Issue status",
      "required": false,
      "enum_values": [
        {"name": "Open", "label": "Open"},
        {"name": "Closed", "label": "Closed"},
        {"name": "In Progress", "label": "In Progress"}
      ]
    }
  ],
  "relationship_fields": [
    {
      "name": "OPSS-Iss:Assoc-Control",
      "label": "Associated Controls",
      "data_type": "MULTI_VALUE_ID_TYPE",
      "is_relationship": true,
      "relationship_type": "multiple",
      "target_type": "SOXControl",
      "description": "Controls associated with this issue"
    }
  ],
  "hierarchical_relationships": [
    {
      "direction": "parent",
      "type": "SOXBusEntity",
      "join_function": "CHILD",
      "join_syntax": "FROM [SOXIssue] JOIN [SOXBusEntity] ON CHILD([SOXIssue])"
    }
  ]
}

The JSON structure provides:

• Clear field categorization (fields vs relationship_fields)
• Explicit enum values for validation
• Relationship metadata (target types, cardinality)
• Hierarchical relationship syntax for queries
• Minified format for efficient transmission (25% size reduction)

4. Advanced Query Capabilities

The execute_openpages_query tool supports sophisticated SQL-like operations:

• Standard operators: =, <>, <, >, <=, >=, LIKE, IN
• Logical operators: AND, OR, NOT
• Text search: CONTAINS(), NOT CONTAINS()
• Sorting: ORDER BY [Field] ASC/DESC
• Pagination: LIMIT n OFFSET n
• Hierarchical queries: JOIN with PARENT(), CHILD(), ANCESTOR(), DESCENDANT() predicates

Benefits of Using Ontology-Based Tools

1. Reduced Cognitive Load for AI Agents

This reduction is particularly important for AI agents, which must evaluate all available tools when deciding how to respond to user requests. Fewer tools mean faster decision-making and more accurate tool selection.

2. Automatic Validation

Every operation is validated against the live OpenPages schema:

• Field names are verified
• Data types are checked
• Enum values are validated
• Required fields are enforced
• Relationship targets are confirmed

This prevents errors before they happen and provides clear, actionable feedback when something's wrong.

3. Future-Proof Flexibility

Add a new object type to your OpenPages instance? The ontology-based tools automatically support it—no code changes required. The schema is discovered dynamically, so your AI agents instantly gain the ability to work with new types.

4. Consistent Interface Across Object Types

All object types use the same tool interface, making it easier for AI agents to learn patterns and apply them consistently. Once an agent knows how to create an Issue, it knows how to create a Control, Risk, or any other object type. This consistency is especially valuable in the OpenPages context, where custom object types and field groups can vary significantly between installations.

5. Performance Optimization for AI Workloads

• Compact schemas: 70-90% reduction in data transfer (critical for LLM context windows)
• Smart caching: Schemas read once per session (reduces API calls and latency)
• Efficient queries: Advanced filtering reduces unnecessary data retrieval
• Token efficiency: 80% reduction in AI token usage (directly impacts cost and speed)

These optimizations are specifically tuned for AI agent workflows, where token costs and context window limits are primary concerns.

6. OpenPages-Native Relationship Management

Dedicated tools for creating and removing associations between objects, with built-in understanding of OpenPages relationship semantics:

• Link Issues to Controls with proper cardinality handling
• Associate Risks with Business Entities using Resource IDs
• Connect Use Cases to Regulations with validation
• Build complex object hierarchies using PARENT/CHILD/ANCESTOR/DESCENDANT queries

This goes beyond generic relationship handling to support OpenPages-specific patterns like field groups, multi-value associations, and hierarchical queries.

How to Use Ontology-Based Tools

Getting Started

1. Enable Ontology-Based Mode in your configuration:

{
  "global_settings": {
    "tool_exposure_mode": "ontology_based",
    "namespace": "openpages"
  }
}

2. Configure Your AI Agent to connect to the MCP server:

{
  "mcpServers": {
    "openpages-grc": {
      "url": "http://localhost:8000/mcp",
      "protocol": "streamable_http"
    }
  }
}

Basic Workflow

Understanding Resource Access

MCP clients can access resources in two ways:

1. Automatic Resource Access (Preferred): Most MCP clients (Claude Desktop, Bob, etc.) automatically fetch resources using the standard MCP protocol's resources/read method. This is transparent to the user.
2. Resource Tools (For Compatibility): For clients that don't support standard resource endpoints, we provide list_resources and get_resource tools that offer the same functionality through the tool interface.

Step 1: Discover Available Object Types (once per session)

AI Agent reads: openpages://catalog/object_types
Result: List of all configured object types (SOXIssue, SOXControl, SOXRisk, etc.)

Step 2: Read Object Schema (once per object type)

AI Agent reads: openpages://schema/SOXIssue (compact mode)
Result: Schema with required fields, system fields, and relationships

Step 3: Perform Operations

Create an Issue:
{
  "tool": "openpages_upsert_object",
  "arguments": {
    "object_type": "SOXIssue",
    "operation": "create",
    "name": "Security Vulnerability Found",
    "fields": {
      "OPSS-Iss:Status": "Open",
      "OPSS-Iss:Priority": "High",
      "Description": "Critical security issue requiring immediate attention"
    }
  }
}

Step 4: Query Object

Find issues that have an Open status:
{
  "tool": "execute_openpages_query",
  "arguments": {
    "query": "SELECT [Name], [OPSS-Iss:Status], [OPSS-Iss:Priority] FROM [SOXIssue] WHERE [OPSS-Iss:Status] = 'Open' ORDER BY [OPSS-Iss:Priority] DESC",
    "format": "table"
  }
}

Best Practices

1. Cache Schemas: Read each schema once per session and reuse it
2. Start with Compact Mode: Use compact schemas for initial exploration
3. Validate Before Creating: Check required fields and enum values
4. Use Relationships: Leverage association tools to link related objects
5. Leverage Context: Use OpenPages UI context variables for personalized operations

Real-World Use Cases

Use Case 1: Intelligent Issue Management

An AI agent can help users create issues with proper validation:

• Discovers required fields from schema
• Validates status and priority values
• Suggests related controls to associate
• Links to appropriate business entities

Use Case 2: Cross-Object Analysis

Query across multiple object types to find patterns:

• Issues linked to specific controls
• Risks associated with business entities
• Use cases mapped to regulations
• Hierarchical relationships (parent-child-descendant)

Use Case 3: Iterative Operations

Process multiple objects through sequential operations:

• Query for objects matching criteria
• Update objects one at a time based on query results
• Create associations between objects iteratively
• Generate reports by aggregating query results

Use Case 4: Dynamic Workflows

Adapt to your OpenPages configuration:

• Discover custom fields automatically
• Work with custom object types
• Respect field-level permissions
• Follow workflow stage requirements

Instructing AI Agents to Use Ontology-Based Tools

One of the key advantages of ontology-based tools is that AI agents can be given clear, reusable instructions for working with any OpenPages object type. Here's how to instruct your AI agents:

Core Workflow Instructions

1. Schema Discovery and Caching (Critical for Performance)

Instruct your AI agent to follow this pattern:

2. Start with Compact Mode, Escalate When Needed

ALWAYS start with compact mode for initial schema reads:
- Read: openpages://schema/{ObjectType}?mode=compact
- This returns only required/system fields (70-90% smaller)

Automatically switch to full mode when:
- User asks about a field NOT in compact schema
- User requests enum values for a field
- User wants to see all available fields
- User needs field descriptions or validation rules

3. Efficient Query Construction

When constructing queries:
1. Use cached schema to identify valid field names
2. Verify enum values against schema before querying
3. Use proper field name format (e.g., 'OPSS-Iss:Status' not 'Status')
4. Leverage relationship fields for hierarchical queries

Key Principles for AI Agents

When instructing AI agents to work with ontology-based tools, emphasize:

1. Schema Caching is Mandatory: Never re-read schemas unnecessarily
2. Compact Mode First: Start small, escalate only when needed
3. Validate Against Schema: Use cached schema to validate before API calls
4. Field Name Precision: Use exact field names from schema (case-sensitive)
5. Enum Value Validation: Check enum values against schema before using
6. Relationship Understanding: Use schema to understand parent-child relationships

Benefits of This Approach

By following these instructions, AI agents will:

• Significantly reduce API calls through schema caching
• Process requests 5-10x faster using compact schemas
• Make fewer errors by validating against cached schemas
• Provide better responses with accurate field names and values
• Scale efficiently as new object types are added

Getting Started Today

The ontology-based tools are available now in the OpenPages GRC MCP Server. Here's how to get started:

📺 Watch the Setup Video: See a complete walkthrough of setting up the MCP server and using observability tools in this LinkedIn demonstration.

1. Review the Documentation:
   • Agent Instructions Overview
   • Ontology-Based Mode Guide
   • Resource Schema Format
2. Deploy the Server:
   • Follow the demo in the LinkedIn video and the instructions in the repo
3. Configure Your AI Agent:
   • Claude Desktop, Bob, or custom MCP clients
   • Point to your server's /mcp endpoint
   • Start exploring your GRC data
4. Explore Sample Implementations:
   • Check the samples/ directory for example configurations
   • Review test cases in tests/ for usage patterns

Conclusion

While ontology-based approaches are well-established in enterprise software, applying them effectively to AI agent interactions requires careful optimization for how Large Language Models process information. Our implementation brings together:

• LLM-optimized schema formats that AI agents can understand naturally
• Intelligent caching strategies that respect token limits and context windows
• Universal tool interfaces that reduce cognitive load on AI decision-making
• OpenPages-specific optimizations for field naming, relationships, and queries

The result is a system that makes it easier for AI agents to work with OpenPages GRC data—whether you're building custom agents, integrating with existing tools, or exploring new ways to leverage AI in your GRC workflows.

What makes this valuable isn't that it's the first ontology-based system, but that it's specifically designed for the unique challenges of AI agent + OpenPages integration: token efficiency, LLM comprehension, dynamic discovery, and OpenPages-native semantics.

Ready to get started? Visit our GitHub repository or check out the complete documentation to begin your journey with ontology-based tools today.

For questions, feedback, or support, please open an issue on GitHub or consult our comprehensive documentation.