[Feature Request]: Comprehensive Tool Docstrings with Self-Contained FQL Guidance

[carlosmmatos]

Summary

Enhance all tool docstrings with documentation including self-contained FQL syntax guidance, enabling AI agents to build valid queries without external resource lookups.

Problem

Current tool descriptions are functional but not optimized for AI agent usage:

• FQL filter parameters reference external resources but lack inline syntax guidance
• AI agents must make additional resource calls to understand FQL syntax
• If the agent fails to build a valid FQL filter, there's no clear fallback path
• Tools lack "when to use" vs "when not to use" guidance for tool selection

Proposed Solution

Implement a hybrid approach for all tool documentation:

1. Primary: Self-Contained Tool Descriptions

Every tool description should include enough information for an AI agent to use it successfully:

For ALL tools:

• "When to Use" scenarios
• "When NOT to Use" / alternative tool suggestions
• Input parameter descriptions with examples
• Output schema documentation
• Common error scenarios and handling

For tools with FQL filters:

• Inline FQL syntax guide with operators
• 5-10 real-world filter examples
• Common filterable fields for that entity type
• Performance tips

2. Fallback: Resource Reference

Include reference to full FQL guide resource as fallback:

For complete FQL syntax, see: falcon://{module}/{operation}/fql-guide

Example Enhanced FQL Parameter Description

filter: str | None = Field(
    default=None,
    description="""FQL filter to limit results. Syntax guide:

    **Operators:**
    - Comparison: severity:>=70, created_timestamp:>'2024-01-01'
    - String match: status:'new', hostname:'PROD*' (wildcard)
    - Contains: description:~'suspicious' (case-insensitive)
    - Range: severity:[70 TO 100]
    - Logical: + (AND), , (OR), ! (NOT)
    
    **Common Fields:** severity, status, hostname, created_timestamp, device.platform_name
    
    **Examples:**
    - High severity new: status:'new'+severity:>=80
    - Recent critical: created_timestamp:>'now-24h'+severity:>=90
    - Windows hosts: device.platform_name:'Windows'+!status:'closed'
    
    **Tip:** Start with time constraints for better performance.
    
    Full syntax reference: falcon://detections/search/fql-guide
    """
)

Files Affected

• All 11 module files in falcon_mcp/modules/ (39+ tools)
• Priority focus on FQL-enabled tools: detections, incidents, hosts, intel, spotlight, discover, cloud, serverless, sensor_usage

Acceptance Criteria

• All tools have "When to Use" and "When NOT to Use" sections
• All FQL filter parameters have inline syntax guide
• Each FQL-enabled tool includes 5-10 real-world filter examples
• Common filterable fields documented per entity type
• Resource URI included as fallback reference
• Output schema documented for all tools
• Unit tests verify docstring completeness