trustgraph/docs/tech-specs/tool-group.md

TrustGraph Tool Group System

Technical Specification v1.0

Executive Summary

This specification defines a tool grouping system for TrustGraph agents that allows fine-grained control over which tools are available for specific requests. The system introduces group-based tool filtering through configuration and request-level specification, enabling better security boundaries, resource management, and functional partitioning of agent capabilities.

1. Overview

1.1 Problem Statement

Currently, TrustGraph agents have access to all configured tools regardless of request context or security requirements. This creates several challenges:

• Security Risk: Sensitive tools (e.g., data modification) are available even for read-only queries
• Resource Waste: Complex tools are loaded even when simple queries don't require them
• Functional Confusion: Agents may select inappropriate tools when simpler alternatives exist
• Multi-tenant Isolation: Different user groups need access to different tool sets

1.2 Solution Overview

The tool group system introduces:

1. Group Classification: Tools are tagged with group memberships during configuration
2. Request-level Filtering: AgentRequest specifies which tool groups are permitted
3. Runtime Enforcement: Agents only have access to tools matching the requested groups
4. Flexible Grouping: Tools can belong to multiple groups for complex scenarios

2. Schema Changes

2.1 Tool Configuration Schema Enhancement

The existing tool configuration is enhanced with a group field:

Before:

{
  "name": "knowledge-query",
  "type": "knowledge-query", 
  "description": "Query the knowledge graph"
}

After:

{
  "name": "knowledge-query",
  "type": "knowledge-query",
  "description": "Query the knowledge graph",
  "group": ["read-only", "knowledge", "basic"]
}

Group Field Specification:

• group: Array(String) - List of groups this tool belongs to
• Optional: Tools without group field belong to "default" group
• Multi-membership: Tools can belong to multiple groups
• Case-sensitive: Group names are exact string matches

2.2 AgentRequest Schema Enhancement

The AgentRequest schema in trustgraph-base/trustgraph/schema/services/agent.py is enhanced:

Current AgentRequest:

• question: String - User query
• plan: String - Execution plan
• state: String - Agent state
• history: Array(AgentStep) - Execution history

Enhanced AgentRequest:

• question: String - User query
• plan: String - Execution plan
• state: String - Agent state
• history: Array(AgentStep) - Execution history
• group: Array(String) - NEW - Tool groups allowed for this request

Group Field Behavior:

• Optional: If not specified, defaults to ["default"]
• Intersection: Only tools matching at least one specified group are available
• Empty array: No tools available (agent can only use internal reasoning)
• Wildcard: Special group "*" grants access to all tools

3. Tool Group Categories

3.1 Predefined Group Categories

Security-Based Groups:

• read-only: Tools that only read data (GraphQuery, KnowledgeQuery)
• write: Tools that modify data (GraphUpdate, DocumentStore)
• admin: Administrative tools (SystemConfig, UserManagement)

Functional Groups:

• knowledge: Knowledge graph operations
• text: Text processing and completion
• search: Search and retrieval operations
• compute: Computation and analysis tools

Complexity Groups:

• basic: Simple, fast tools for common operations
• advanced: Complex tools for specialized tasks
• experimental: Beta/experimental tools

Resource Groups:

• local: Tools that run locally
• remote: Tools that require external services
• expensive: Resource-intensive tools

3.2 Custom Group Examples

Organizations can define domain-specific groups:

{
  "financial-tools": ["stock-query", "portfolio-analysis"],
  "medical-tools": ["diagnosis-assist", "drug-interaction"],
  "legal-tools": ["contract-analysis", "case-search"]
}

4. Implementation Details

4.1 Tool Loading and Filtering

Configuration Phase:

1. All tools are loaded from configuration with their group assignments
2. Tools without explicit groups are assigned to "default" group
3. Group membership is validated and stored in tool registry

Request Processing Phase:

1. AgentRequest arrives with optional group specification
2. Agent filters available tools based on group intersection
3. Only matching tools are passed to agent execution context
4. Agent operates with filtered tool set throughout request lifecycle

4.2 Group Resolution Logic

For each configured tool:
  tool_groups = tool.group || ["default"]
  
For each request:
  requested_groups = request.group || ["default"]
  
Tool is available if:
  intersection(tool_groups, requested_groups) is not empty
  OR
  "*" in requested_groups

4.3 Agent Integration Points

ReAct Agent:

• Tool filtering occurs in agent_manager.py during tool registry creation
• Available tools list is pre-filtered before plan generation
• No changes to execution logic required

Confidence-Based Agent:

• Tool filtering occurs in planner.py during plan generation
• ExecutionStep validation ensures only available tools are used
• Flow controller enforces tool availability at runtime

5. Configuration Examples

5.1 Tool Configuration with Groups

tool:
  knowledge-query:
    type: knowledge-query
    name: "Knowledge Graph Query"
    description: "Query the knowledge graph for entities and relationships"
    group: ["read-only", "knowledge", "basic"]
    
  graph-update:
    type: graph-update
    name: "Graph Update"
    description: "Add or modify entities in the knowledge graph"
    group: ["write", "knowledge", "admin"]
    
  text-completion:
    type: text-completion
    name: "Text Completion"
    description: "Generate text using language models"
    group: ["read-only", "text", "basic"]
    
  complex-analysis:
    type: mcp-tool
    name: "Complex Analysis Tool"
    description: "Perform complex data analysis"
    group: ["advanced", "compute", "expensive"]
    mcp_tool_id: "analysis-server"

5.2 Request Examples

Read-only Knowledge Query:

{
  "question": "What entities are connected to Company X?",
  "group": ["read-only", "knowledge"]
}

Available tools: knowledge-query only

Administrative Task:

{
  "question": "Update the company profile and analyze impact",
  "group": ["write", "knowledge", "compute"]
}

Available tools: graph-update, complex-analysis

Unrestricted Access:

{
  "question": "Perform comprehensive analysis",
  "group": ["*"]
}

Available tools: All configured tools

Basic Operations Only:

{
  "question": "Simple information lookup",
  "group": ["basic"]
}

Available tools: knowledge-query, text-completion

6. Security Considerations

6.1 Access Control Integration

Gateway-Level Filtering:

• Gateway can enforce group restrictions based on user permissions
• Prevent elevation of privileges through request manipulation
• Audit trail includes requested and granted tool groups

Example Gateway Logic:

user_permissions = get_user_permissions(request.user_id)
allowed_groups = user_permissions.tool_groups
requested_groups = request.group

# Validate request doesn't exceed permissions
if not is_subset(requested_groups, allowed_groups):
    reject_request("Insufficient permissions for requested tool groups")

6.2 Audit and Monitoring

Enhanced Audit Trail:

• Log requested tool groups per request
• Track tool usage by group membership
• Monitor unauthorized group access attempts
• Alert on unusual group usage patterns

7. Migration Strategy

7.1 Backward Compatibility

Phase 1: Additive Changes

• Add optional group field to tool configurations
• Add optional group field to AgentRequest schema
• Default behavior: All existing tools belong to "default" group
• Existing requests without group field use "default" group

Existing Behavior Preserved:

• Tools without group configuration continue to work
• Requests without group specification access all tools
• No breaking changes to existing deployments

7.2 Migration Path

Step 1: Schema Deployment

• Deploy enhanced schemas with optional fields
• Verify existing tools and requests continue to work

Step 2: Tool Classification

• Gradually add group classifications to tool configurations
• Start with security-critical tools (read-only vs write)
• Expand to functional and complexity groups

Step 3: Request Integration

• Update client applications to specify appropriate groups
• Implement gateway-level access control
• Monitor usage patterns and refine groups

Step 4: Enforcement

• Gradually tighten default permissions
• Eventually require explicit group specification for new deployments

8. Monitoring and Observability

8.1 New Metrics

Tool Group Usage:

• agent_tool_group_requests_total - Counter of requests by group
• agent_tool_group_availability - Gauge of tools available per group
• agent_filtered_tools_count - Histogram of tool count after filtering

Security Metrics:

• agent_group_access_denied_total - Counter of unauthorized group access
• agent_privilege_escalation_attempts_total - Counter of suspicious requests

8.2 Logging Enhancements

Request Logging:

{
  "request_id": "req-123",
  "requested_groups": ["read-only", "knowledge"],
  "available_tools": ["knowledge-query"],
  "filtered_tools": ["graph-update", "admin-tool"],
  "execution_time": "1.2s"
}

9. Testing Strategy

9.1 Unit Tests

Tool Filtering Logic:

• Test group intersection calculations
• Verify default group assignment
• Test wildcard group behavior
• Validate empty group handling

Configuration Validation:

• Test tool loading with various group configurations
• Verify schema validation for invalid group specifications
• Test backward compatibility with existing configurations

9.2 Integration Tests

Agent Behavior:

• Verify agents only see filtered tools
• Test request execution with various group combinations
• Validate error handling when no tools are available

Security Testing:

• Test privilege escalation prevention
• Verify audit trail accuracy
• Test gateway integration with user permissions

9.3 End-to-End Scenarios

Multi-tenant Usage:

Scenario: Different users with different tool access
Given: User A has "read-only" permissions
  And: User B has "write" permissions
When: Both request knowledge operations
Then: User A gets filtered tool set
  And: User B gets full tool set
  And: All usage is properly audited

10. Performance Considerations

10.1 Tool Loading Impact

Configuration Loading:

• Group metadata is loaded once at startup
• Minimal memory overhead per tool
• No impact on tool initialization time

Request Processing:

• Tool filtering occurs once per request
• O(n) complexity where n = number of configured tools
• Negligible impact for typical tool counts (< 100)

10.2 Optimization Strategies

Pre-computed Group Sets:

• Cache tool sets by group combination
• Avoid repeated filtering for common group patterns
• Memory vs computation tradeoff

Lazy Loading:

• Load tool implementations only when needed
• Reduce startup time for deployments with many tools
• Dynamic tool registration based on group requirements

11. Future Enhancements

11.1 Dynamic Group Assignment

Context-Aware Grouping:

• Assign tools to groups based on request context
• Time-based group availability (business hours only)
• Load-based group restrictions (expensive tools during low usage)

11.2 Group Hierarchies

Nested Group Structure:

{
  "knowledge": {
    "read": ["knowledge-query", "entity-search"],
    "write": ["graph-update", "entity-create"]
  }
}

11.3 Tool Recommendations

Group-Based Suggestions:

• Suggest optimal tool groups for request types
• Learn from usage patterns to improve recommendations
• Provide fallback groups when preferred tools are unavailable

12. Open Questions

1. Group Validation: Should invalid group names in requests cause hard failures or warnings?

2. Group Discovery: Should the system provide an API to list available groups and their tools?

3. Dynamic Groups: Should groups be configurable at runtime or only at startup?

4. Group Inheritance: Should tools inherit groups from their parent categories or implementations?

5. Performance Monitoring: What additional metrics are needed to track group-based tool usage effectively?

13. Conclusion

The tool group system provides:

• Security: Fine-grained access control over agent capabilities
• Performance: Reduced tool loading and selection overhead
• Flexibility: Multi-dimensional tool classification
• Compatibility: Seamless integration with existing agent architectures

This system enables TrustGraph deployments to better manage tool access, improve security boundaries, and optimize resource usage while maintaining full backward compatibility with existing configurations and requests.