AGENT_TOOL_SELECTION_GUIDE.md

Agent Tool Selection Guide

Quick Decision Tree

Need type information or cross-file analysis?
├── YES → Use Semantic Tools (find-*)
└── NO → Need complex pattern matching?
    ├── YES → Use Syntactic Tools (query-syntax, navigate, get-ast)
    └── NO → Use Semantic Tools for simplicity

Tool Categories at a Glance

Semantic Tools (find-* family)

Best for: Type information, symbol resolution, cross-file references, inheritance relationships Speed: Slower (requires compilation) Pattern matching: Simple wildcards only Returns: Rich metadata with types and relationships

Syntactic Tools (SpelunkPath-based)

Best for: Code patterns, structural queries, expression-level analysis, code style checks Speed: Fast (no compilation needed) Pattern matching: Complex XPath-style queries Returns: AST nodes with optional semantic enrichment

Common Scenarios

1. "Find all methods that override a base class method"

Use: spelunk-find-method (semantic)

{
  "tool": "spelunk-find-method",
  "pattern": "*",
  "includeOverrides": true
}

Why: Requires understanding inheritance relationships across files

2. "Find all null comparisons in if statements"

Use: spelunk-query-syntax (syntactic)

{
  "tool": "spelunk-query-syntax",
  "roslynPath": "//if-statement//binary-expression[@operator='==' and @right-text='null']"
}

Why: Pattern-based search within syntax structure

3. "Find all implementations of IDisposable"

Use: spelunk-find-implementations (semantic)

{
  "tool": "spelunk-find-implementations",
  "interfaceName": "IDisposable"
}

Why: Requires type resolution and inheritance analysis

4. "Find all async methods without ConfigureAwait"

Use: spelunk-query-syntax (syntactic)

{
  "tool": "spelunk-query-syntax",
  "roslynPath": "//method[@async]//await-expression[not(invocation[@name='ConfigureAwait'])]"
}

Why: Structural pattern within method bodies

5. "Find what type a variable is"

Use: spelunk-query-syntax with semantic enrichment

{
  "tool": "spelunk-query-syntax",
  "roslynPath": "//variable[@name='customer']",
  "includeSemanticInfo": true
}

Why: Need syntax location but also type information

Performance Considerations

Use Semantic Tools When:

• First-time analysis of a project
• Type information is essential
• Cross-file relationships matter
• Working with compiled, stable code

Use Syntactic Tools When:

• Repeated queries on same codebase
• Analyzing code style or patterns
• Working with code that might not compile
• Need sub-second response times

Multi-Language Considerations

C# and VB.NET

Both languages work with all tools through Roslyn:

• Semantic tools abstract language differences
• SpelunkPath queries use language-agnostic node types where possible

F#

Currently requires special handling:

• Semantic tools route to F#-specific implementations
• Use FSharpPath syntax instead of SpelunkPath
• Some cross-language features limited

Advanced Patterns

Combining Tools

1. Use semantic tool to find symbols
2. Use syntactic tool to analyze usage patterns

Example: Find all ToString() overrides that don't call base

// Step 1: Find overrides
{
  "tool": "spelunk-find-method",
  "pattern": "ToString",
  "includeOverrides": true
}

// Step 2: Check implementation
{
  "tool": "spelunk-query-syntax",
  "file": "result.file",
  "roslynPath": "//method[ToString]/block[not(.//base-expression)]"
}

Semantic Enrichment

When you need both syntax patterns and type info:

{
  "tool": "spelunk-query-syntax",
  "roslynPath": "//invocation[@name='Process']",
  "includeSemanticInfo": true
}

Returns syntax nodes with added semantic data:

{
  "node": { "type": "InvocationExpression", "text": "Process(order)" },
  "semanticInfo": {
    "symbol": "OrderService.Process(Order)",
    "returnType": "ProcessResult",
    "isAsync": false
  }
}

Decision Matrix

Task	Recommended Tool	Reasoning
Find method by name	find-method	Simple, returns rich metadata
Find complex patterns	query-syntax	XPath flexibility needed
Find type references	find-type-references	Cross-file semantic analysis
Check code style	query-syntax	Pattern-based, no compilation
Find unused code	find-references + analysis	Semantic understanding required
Navigate from position	navigate	Position-based with XPath nav
Understand code structure	get-ast	Syntax tree visualization
Find inheritance chain	find-type	Semantic relationships
Find string literals	query-syntax	Simple syntax pattern
Find API usage	find-references	Semantic symbol resolution

Error Handling

Semantic Tool Failures

• Compilation errors: Tool returns partial results or fails
• Missing references: May not resolve external types
• Solution: Fix compilation or use syntactic tools

Syntactic Tool Limitations

• No type info: Can't distinguish overloads
• No cross-file: Can't follow references
• Solution: Use includeSemanticInfo or switch to semantic tools

Best Practices for Agents

1. Start with intent: What information does the user actually need?
2. Consider compilation state: Is the code likely to compile?
3. Optimize for speed: Use syntactic when semantic isn't required
4. Cache patterns: Reuse SpelunkPath queries for similar requests
5. Fail gracefully: Have fallback from semantic to syntactic

Quick Reference

Semantic Tools

• spelunk-find-method - Methods with full signatures
• spelunk-find-property - Properties with types
• spelunk-find-class - Classes with inheritance
• spelunk-find-interface - Interfaces with members
• spelunk-find-type - Any type definition
• spelunk-find-implementations - Interface/abstract implementations
• spelunk-find-references - Symbol usage across files
• spelunk-find-type-references - Type usage locations

Syntactic Tools

• spelunk-query-syntax - XPath queries on AST
• spelunk-navigate - Navigate from position using axes
• spelunk-get-ast - Get syntax tree structure
• spelunk-find-in-project - Text search (fallback)

Hybrid Approach

All syntactic tools support includeSemanticInfo: true for enriched results combining syntax patterns with semantic data.