awesome-copilot/instructions/cpp-language-service-tools.instructions.md

description: You are an expert at using C++ language service tools (GetSymbolReferences_CppTools, GetSymbolInfo_CppTools, GetSymbolCallHierarchy_CppTools). Instructions for calling C++ Tools for Copilot. When working with C++ code, you have access to powerful language service tools that provide accurate, IntelliSense-powered analysis. Always prefer these tools over manual code inspection, text search, or guessing. applyTo: **/.cpp, **/.h, **/.hpp, **/.cc, **/.cxx, **/.c

Available C++ Tools

You have access to three specialized C++ tools:

1. GetSymbolInfo_CppTools - Find symbol definitions and get type details
2. GetSymbolReferences_CppTools - Find ALL references to a symbol
3. GetSymbolCallHierarchy_CppTools - Analyze function call relationships

---

Mandatory Tool Usage Rules

Rule 1: ALWAYS Use GetSymbolReferences_CppTools for Symbol Usages

NEVER rely on manual code inspection, vscode_listCodeUsages, grep_search, or read_file to find where a symbol is used.

ALWAYS call GetSymbolReferences_CppTools when:

• Renaming any symbol (function, variable, class, method, etc.)
• Changing function signatures
• Refactoring code
• Understanding symbol impact
• Finding all call sites
• Identifying usage patterns
• Any task involving "find all uses/usages/references/calls"

Why: GetSymbolReferences_CppTools uses C++ IntelliSense and understands:

• Overloaded functions
• Template instantiations
• Qualified vs unqualified names
• Member function calls
• Inherited member usage
• Preprocessor-conditional code

Text search tools will miss these or produce false positives.

Rule 2: ALWAYS Use GetSymbolCallHierarchy_CppTools for Function Changes

Before modifying any function signature, ALWAYS call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers.

Examples:

• Adding/removing function parameters
• Changing parameter types
• Changing return types
• Making functions virtual
• Converting to template functions

Why: This ensures you update ALL call sites, not just the ones you can see.

Rule 3: ALWAYS Use GetSymbolInfo_CppTools to Understand Symbols

Before working with unfamiliar code, ALWAYS call GetSymbolInfo_CppTools to:

• Find where a symbol is defined
• Understand class/struct memory layout
• Get type information
• Locate declarations

NEVER assume you know what a symbol is without checking.

---

Parameter Usage Guidelines

Symbol Names

• ALWAYS REQUIRED: Provide the symbol name
• Can be unqualified (MyFunction), partially qualified (MyClass::MyMethod), or fully qualified (MyNamespace::MyClass::MyMethod)
• If you have a line number, the symbol should match what appears on that line

File Paths

• STRONGLY PREFERRED: Always provide absolute file paths when available
  • ✅ Good: C:\Users\Project\src\main.cpp
  • ❌ Avoid: src\main.cpp (requires resolution, may fail)
• If you have access to a file path, include it
• If working with user-specified files, use their exact path

Line Numbers

• CRITICAL: Line numbers are 1-based, NOT 0-based
• MANDATORY WORKFLOW when you need a line number:
  1. First call read_file to search for the symbol
  2. Locate the symbol in the output
  3. Note the EXACT line number from the output
  4. VERIFY the line contains the symbol
  5. Only then call the C++ tool with that line number
• NEVER guess or estimate line numbers
• If you don't have a line number, omit it - the tools will find the symbol

Minimal Information Strategy

Start with minimal information and add more only if needed:

1. First attempt: Symbol name only
2. If ambiguous: Symbol name + file path
3. If still ambiguous: Symbol name + file path + line number (after using read_file)

---

Common Workflows

Renaming a Symbol

CORRECT workflow:
1. Call GetSymbolReferences_CppTools with symbol name (and file path if available)
2. Review ALL references returned
3. Update symbol at definition location
4. Update symbol at ALL reference locations

INCORRECT workflow:
❌ Using vscode_listCodeUsages or grep_search to find usages
❌ Manually inspecting a few files
❌ Assuming you know all the usages

Changing a Function Signature

CORRECT workflow:
1. Call GetSymbolInfo_CppTools to locate the function definition
2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers
3. Call GetSymbolReferences_CppTools to catch any additional references (function pointers, etc.)
4. Update function definition
5. Update ALL call sites with new signature

INCORRECT workflow:
❌ Changing the function without finding callers
❌ Only updating visible call sites
❌ Using text search to find calls

Understanding Unfamiliar Code

CORRECT workflow:
1. Call GetSymbolInfo_CppTools on key types/functions to understand definitions
3. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to understand what a function does
4. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to understand where a function is used

INCORRECT workflow:
❌ Reading code manually without tool assistance
❌ Making assumptions about symbol meanings
❌ Skipping hierarchy analysis

Analyzing Function Dependencies

CORRECT workflow:
1. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to see what the function calls (outgoing)
2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to see what calls the function (incoming)
3. Use this to understand code flow and dependencies

INCORRECT workflow:
❌ Manually reading through function body
❌ Guessing at call patterns

---

Error Handling and Recovery

When You Get an Error Message

All error messages contain specific recovery instructions. ALWAYS follow them exactly.

"Symbol name is not valid" Error

Error: "The symbol name is not valid: it is either empty or null. Find a valid symbol name. Then call the [tool] tool again"

Recovery:
1. Ensure you provided a non-empty symbol name
2. Check that the symbol name is spelled correctly
3. Retry with valid symbol name

"File could not be found" Error

Error: "A file could not be found at the specified path. Compute the absolute path to the file. Then call the [tool] tool again."

Recovery:
1. Convert relative path to absolute path
2. Verify file exists in the workspace
3. Use exact path from user or file system
4. Retry with absolute path

"No results found" Message

Message: "No results found for the symbol '[symbol_name]'."

This is NOT an error - it means:
- The symbol exists and was found
- But it has no references/calls/hierarchy (depending on tool)
- This is valid information - report it to the user

---

Tool Selection Decision Tree

Question: Do I need to find where a symbol is used/called/referenced?

• ✅ YES → Use GetSymbolReferences_CppTools
• ❌ NO → Continue

Question: Am I changing a function signature or analyzing function calls?

• ✅ YES → Use GetSymbolCallHierarchy_CppTools
  • Finding callers? → callsFrom=false
  • Finding what it calls? → callsFrom=true
• ❌ NO → Continue

Question: Do I need to find a definition or understand a type?

• ✅ YES → Use GetSymbolInfo_CppTools
• ❌ NO → You may not need a C++ tool for this task

---

Critical Reminders

DO:

• ✅ Call GetSymbolReferences_CppTools for ANY symbol usage search
• ✅ Call GetSymbolCallHierarchy_CppTools before function signature changes
• ✅ Use read_file to find line numbers before specifying them
• ✅ Provide absolute file paths when available
• ✅ Follow error message instructions exactly
• ✅ Trust tool results over manual inspection
• ✅ Use minimal parameters first, add more if needed
• ✅ Remember line numbers are 1-based

DO NOT:

• ❌ Use vscode_listCodeUsages, grep_search, or read_file to find symbol usages
• ❌ Manually inspect code to find references
• ❌ Guess line numbers
• ❌ Assume symbol uniqueness without checking
• ❌ Ignore error messages
• ❌ Skip tool usage to save time
• ❌ Use 0-based line numbers
• ❌ Batch multiple unrelated symbol operations
• ❌ Make changes without finding all affected locations

---

Examples of Correct Usage

Example 1: User asks to rename a function

User: "Rename the function ProcessData to HandleData"

CORRECT response:
1. Call GetSymbolReferences_CppTools("ProcessData")
2. Review all reference locations
3. Update function definition
4. Update all call sites shown in results
5. Confirm all changes made

INCORRECT response:
❌ Using grep_search to find "ProcessData"
❌ Only updating files the user mentioned
❌ Assuming you found all usages manually

Example 2: User asks to add a parameter to a function

User: "Add a parameter 'bool verbose' to the LogMessage function"

CORRECT response:
1. Call GetSymbolInfo_CppTools("LogMessage") to find definition
2. Call GetSymbolCallHierarchy_CppTools("LogMessage", callsFrom=false) to find all callers
3. Call GetSymbolReferences_CppTools("LogMessage") to catch any function pointer uses
4. Update function definition
5. Update ALL call sites with new parameter

INCORRECT response:
❌ Only updating the definition
❌ Updating only obvious call sites
❌ Not using call_hierarchy tool

Example 3: User asks to understand a function

User: "What does the Initialize function do?"

CORRECT response:
1. Call GetSymbolInfo_CppTools("Initialize") to find definition and location
2. Call GetSymbolCallHierarchy_CppTools("Initialize", callsFrom=true) to see what it calls
3. Read the function implementation
4. Explain based on code + call hierarchy

INCORRECT response:
❌ Only reading the function body
❌ Not checking what it calls
❌ Guessing at behavior

---

Performance and Best Practices

Efficient Tool Usage

• Call tools in parallel when analyzing multiple independent symbols
• Use file paths to speed up symbol resolution
• Provide context to narrow searches

Iterative Refinement

• If first tool call is ambiguous, add file path
• If still ambiguous, use read_file to find exact line
• Tools are designed for iteration

Understanding Results

• Empty results are valid: "No results found" means the symbol has no references/calls
• Multiple results are common: C++ has overloading, templates, namespaces
• Trust the tools: IntelliSense knows C++ semantics better than text search

---

Integration with Other Tools

When to use read_file

• ONLY for finding line numbers before calling C++ tools
• ONLY for reading implementation details after locating symbols
• NEVER for finding symbol usages (use GetSymbolReferences_CppTools instead)

When to use vscode_listCodeUsages/grep_search

• Finding string literals or comments
• Searching non-C++ files
• Pattern matching in configuration files
• NEVER for finding C++ symbol usages

When to use semantic_search

• Finding code based on conceptual queries
• Locating relevant files in large codebases
• Understanding project structure
• Then use C++ tools for precise symbol analysis

---

Summary

The golden rule: When working with C++ code, think "tool first, manual inspection later."

1. Symbol usages? → GetSymbolReferences_CppTools
2. Function calls? → GetSymbolCallHierarchy_CppTools
3. Symbol definition? → GetSymbolInfo_CppTools

These tools are your primary interface to C++ code understanding. Use them liberally and often. They are fast, accurate, and understand C++ semantics that text search cannot capture.

Your success metric: Did I use the right C++ tool for every symbol-related task?