[Feature Request]: Add Response Detail Levels and Character Limits

[carlosmmatos]

Summary

Implement configurable response detail levels (raw, compact, summary) and enforce character limits to prevent overwhelming LLM context windows.

Problem

Current tool responses return full API payloads which can:

• Exceed LLM context window limits causing truncation or errors
• Include unnecessary fields that consume tokens without adding value
• Make it difficult for AI agents to extract key information quickly

Proposed Solution

1. Response Detail Levels

Add a detail_level parameter to search/get tools with three options. The parameter description must be self-documenting so LLMs can choose the appropriate level:

detail_level: str = Field(
    default="compact",
    description="""Response detail level controlling which fields are returned:

    - 'summary': Minimal fields for quick overview (id, severity, status, hostname)
      Use when: Listing items, counting, or initial triage
      
    - 'compact': Key fields for analysis (adds timestamps, tactics, techniques, behaviors)
      Use when: Investigating specific items or building reports
      
    - 'raw': Complete API response with all available fields
      Use when: Deep investigation requiring full context or debugging
    
    Default: 'compact' (recommended for most use cases)
    """
)

Example Field Sets for Detections:

Level	Fields Included
summary	detection_id, severity, status, hostname
compact	+ created_timestamp, tactic, technique, behavior_count, device_id
raw	All API fields

2. Character Limit Enforcement

Implement a 25,000 character limit with graceful truncation:

• Measure response size before returning
• If exceeds limit, reduce items (not truncate mid-field)
• Include clear warning message with guidance

⚠️ Response truncated from 150 to 45 items due to size limit.
Use 'offset' parameter or add filters to retrieve remaining data.

Files Affected

• falcon_mcp/common/constants.py (NEW) - CHARACTER_LIMIT constant, DetailLevel enum
• falcon_mcp/common/utils.py - Add truncate_response() and format_response_level() functions
• falcon_mcp/modules/base.py - Apply truncation and detail level in base methods
• All module files - Define compact/summary field mappings per entity type

Acceptance Criteria

• detail_level parameter added with self-documenting description
• Default is compact (not raw) to optimize for common use cases
• Field mappings defined for all entity types (detections, hosts, incidents, etc.)
• Character limit enforced with item-level truncation (not mid-field)
• Truncation warning includes actionable guidance
• Unit tests for all detail levels and truncation scenarios