{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"cpp-language-service-tools","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 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.**\napplyTo: \"**/*.cpp, **/*.h, **/*.hpp, **/*.cc, **/*.cxx, **/*.c\"\n---\n\n## Available C++ Tools\n\nYou have access to three specialized C++ tools:\n\n1. **`GetSymbolInfo_CppTools`** - Find symbol definitions and get type details\n2. **`GetSymbolReferences_CppTools`** - Find ALL references to a symbol\n3. **`GetSymbolCallHierarchy_CppTools`** - Analyze function call relationships\n\n---\n\n## Mandatory Tool Usage Rules\n\n### Rule 1: ALWAYS Use GetSymbolReferences_CppTools for Symbol Usages\n\n**NEVER** rely on manual code inspection, `vscode_listCodeUsages`, `grep_search`, or `read_file` to find where a symbol is used.\n\n**ALWAYS** call `GetSymbolReferences_CppTools` when:\n\n- Renaming any symbol (function, variable, class, method, etc.)\n- Changing function signatures\n- Refactoring code\n- Understanding symbol impact\n- Finding all call sites\n- Identifying usage patterns\n- Any task involving \"find all uses/usages/references/calls\"\n\n**Why**: `GetSymbolReferences_CppTools` uses C++ IntelliSense and understands:\n\n- Overloaded functions\n- Template instantiations\n- Qualified vs unqualified names\n- Member function calls\n- Inherited member usage\n- Preprocessor-conditional code\n\nText search tools will miss these or produce false positives.\n\n### Rule 2: ALWAYS Use GetSymbolCallHierarchy_CppTools for Function Changes\n\nBefore modifying any function signature, **ALWAYS** call `GetSymbolCallHierarchy_CppTools` with `callsFrom=false` to find all callers.\n\n**Examples**:\n\n- Adding/removing function parameters\n- Changing parameter types\n- Changing return types\n- Making functions virtual\n- Converting to template functions\n\n**Why**: This ensures you update ALL call sites, not just the ones you can see.\n\n### Rule 3: ALWAYS Use GetSymbolInfo_CppTools to Understand Symbols\n\nBefore working with unfamiliar code, **ALWAYS** call `GetSymbolInfo_CppTools` to:\n\n- Find where a symbol is defined\n- Understand class/struct memory layout\n- Get type information\n- Locate declarations\n\n**NEVER** assume you know what a symbol is without checking.\n\n---\n\n## Parameter Usage Guidelines\n\n### Symbol Names\n\n- **ALWAYS REQUIRED**: Provide the symbol name\n- Can be unqualified (`MyFunction`), partially qualified (`MyClass::MyMethod`), or fully qualified (`MyNamespace::MyClass::MyMethod`)\n- If you have a line number, the symbol should match what appears on that line\n\n### File Paths\n\n- **STRONGLY PREFERRED**: Always provide absolute file paths when available\n  - ✅ Good: `C:\\Users\\Project\\src\\main.cpp`\n  - ❌ Avoid: `src\\main.cpp` (requires resolution, may fail)\n- If you have access to a file path, include it\n- If working with user-specified files, use their exact path\n\n### Line Numbers\n\n- **CRITICAL**: Line numbers are 1-based, NOT 0-based\n- **MANDATORY WORKFLOW** when you need a line number:\n  1. First call `read_file` to search for the symbol\n  2. Locate the symbol in the output\n  3. Note the EXACT line number from the output\n  4. VERIFY the line contains the symbol\n  5. Only then call the C++ tool with that line number\n- **NEVER** guess or estimate line numbers\n- If you don't have a line number, omit it - the tools will find the symbol\n\n### Minimal Information Strategy\n\nStart with minimal information and add more only if needed:\n\n1. **First attempt**: Symbol name only\n2. **If ambiguous**: Symbol name + file path\n3. **If still ambiguous**: Symbol name + file path + line number (after using `read_file`)\n\n---\n\n## Common Workflows\n\n### Renaming a Symbol\n\n```\nCORRECT workflow:\n1. Call GetSymbolReferences_CppTools with symbol name (and file path if available)\n2. Review ALL references returned\n3. Update symbol at definition location\n4. Update symbol at ALL reference locations\n\nINCORRECT workflow:\n❌ Using vscode_listCodeUsages or grep_search to find usages\n❌ Manually inspecting a few files\n❌ Assuming you know all the usages\n```\n\n### Changing a Function Signature\n\n```\nCORRECT workflow:\n1. Call GetSymbolInfo_CppTools to locate the function definition\n2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to find all callers\n3. Call GetSymbolReferences_CppTools to catch any additional references (function pointers, etc.)\n4. Update function definition\n5. Update ALL call sites with new signature\n\nINCORRECT workflow:\n❌ Changing the function without finding callers\n❌ Only updating visible call sites\n❌ Using text search to find calls\n```\n\n### Understanding Unfamiliar Code\n\n```\nCORRECT workflow:\n1. Call GetSymbolInfo_CppTools on key types/functions to understand definitions\n3. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to understand what a function does\n4. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to understand where a function is used\n\nINCORRECT workflow:\n❌ Reading code manually without tool assistance\n❌ Making assumptions about symbol meanings\n❌ Skipping hierarchy analysis\n```\n\n### Analyzing Function Dependencies\n\n```\nCORRECT workflow:\n1. Call GetSymbolCallHierarchy_CppTools with callsFrom=true to see what the function calls (outgoing)\n2. Call GetSymbolCallHierarchy_CppTools with callsFrom=false to see what calls the function (incoming)\n3. Use this to understand code flow and dependencies\n\nINCORRECT workflow:\n❌ Manually reading through function body\n❌ Guessing at call patterns\n```\n\n---\n\n## Error Handling and Recovery\n\n### When You Get an Error Message\n\n**All error messages contain specific recovery instructions. ALWAYS follow them exactly.**\n\n#### \"Symbol name is not valid\" Error\n\n```\nError: \"The symbol name is not valid: it is either empty or null. Find a valid symbol name. Then call the [tool] tool again\"\n\nRecovery:\n1. Ensure you provided a non-empty symbol name\n2. Check that the symbol name is spelled correctly\n3. Retry with valid symbol name\n```\n\n#### \"File could not be found\" Error\n\n```\nError: \"A file could not be found at the specified path. Compute the absolute path to the file. Then call the [tool] tool again.\"\n\nRecovery:\n1. Convert relative path to absolute path\n2. Verify file exists in the workspace\n3. Use exact path from user or file system\n4. Retry with absolute path\n```\n\n#### \"No results found\" Message\n\n```\nMessage: \"No results found for the symbol '[symbol_name]'.\"\n\nThis is NOT an error - it means:\n- The symbol exists and was found\n- But it has no references/calls/hierarchy (depending on tool)\n- This is valid information - report it to the user\n```\n\n---\n\n## Tool Selection Decision Tree\n\n**Question: Do I need to find where a symbol is used/called/referenced?**\n\n- ✅ YES → Use `GetSymbolReferences_CppTools`\n- ❌ NO → Continue\n\n**Question: Am I changing a function signature or analyzing function calls?**\n\n- ✅ YES → Use `GetSymbolCallHierarchy_CppTools`\n  - Finding callers? → `callsFrom=false`\n  - Finding what it calls? → `callsFrom=true`\n- ❌ NO → Continue\n\n**Question: Do I need to find a definition or understand a type?**\n\n- ✅ YES → Use `GetSymbolInfo_CppTools`\n- ❌ NO → You may not need a C++ tool for this task\n\n---\n\n## Critical Reminders\n\n### DO:\n\n- ✅ Call `GetSymbolReferences_CppTools` for ANY symbol usage search\n- ✅ Call `GetSymbolCallHierarchy_CppTools` before function signature changes\n- ✅ Use `read_file` to find line numbers before specifying them\n- ✅ Provide absolute file paths when available\n- ✅ Follow error message instructions exactly\n- ✅ Trust tool results over manual inspection\n- ✅ Use minimal parameters first, add more if needed\n- ✅ Remember line numbers are 1-based\n\n### DO NOT:\n\n- ❌ Use `vscode_listCodeUsages`, `grep_search`, or `read_file` to find symbol usages\n- ❌ Manually inspect code to find references\n- ❌ Guess line numbers\n- ❌ Assume symbol uniqueness without checking\n- ❌ Ignore error messages\n- ❌ Skip tool usage to save time\n- ❌ Use 0-based line numbers\n- ❌ Batch multiple unrelated symbol operations\n- ❌ Make changes without finding all affected locations\n\n---\n\n## Examples of Correct Usage\n\n### Example 1: User asks to rename a function\n\n```\nUser: \"Rename the function ProcessData to HandleData\"\n\nCORRECT response:\n1. Call GetSymbolReferences_CppTools(\"ProcessData\")\n2. Review all reference locations\n3. Update function definition\n4. Update all call sites shown in results\n5. Confirm all changes made\n\nINCORRECT response:\n❌ Using grep_search to find \"ProcessData\"\n❌ Only updating files the user mentioned\n❌ Assuming you found all usages manually\n```\n\n### Example 2: User asks to add a parameter to a function\n\n```\nUser: \"Add a parameter 'bool verbose' to the LogMessage function\"\n\nCORRECT response:\n1. Call GetSymbolInfo_CppTools(\"LogMessage\") to find definition\n2. Call GetSymbolCallHierarchy_CppTools(\"LogMessage\", callsFrom=false) to find all callers\n3. Call GetSymbolReferences_CppTools(\"LogMessage\") to catch any function pointer uses\n4. Update function definition\n5. Update ALL call sites with new parameter\n\nINCORRECT response:\n❌ Only updating the definition\n❌ Updating only obvious call sites\n❌ Not using call_hierarchy tool\n```\n\n### Example 3: User asks to understand a function\n\n```\nUser: \"What does the Initialize function do?\"\n\nCORRECT response:\n1. Call GetSymbolInfo_CppTools(\"Initialize\") to find definition and location\n2. Call GetSymbolCallHierarchy_CppTools(\"Initialize\", callsFrom=true) to see what it calls\n3. Read the function implementation\n4. Explain based on code + call hierarchy\n\nINCORRECT response:\n❌ Only reading the function body\n❌ Not checking what it calls\n❌ Guessing at behavior\n```\n\n---\n\n## Performance and Best Practices\n\n### Efficient Tool Usage\n\n- Call tools in parallel when analyzing multiple independent symbols\n- Use file paths to speed up symbol resolution\n- Provide context to narrow searches\n\n### Iterative Refinement\n\n- If first tool call is ambiguous, add file path\n- If still ambiguous, use `read_file` to find exact line\n- Tools are designed for iteration\n\n### Understanding Results\n\n- **Empty results are valid**: \"No results found\" means the symbol has no references/calls\n- **Multiple results are common**: C++ has overloading, templates, namespaces\n- **Trust the tools**: IntelliSense knows C++ semantics better than text search\n\n---\n\n## Integration with Other Tools\n\n### When to use read_file\n\n- **ONLY** for finding line numbers before calling C++ tools\n- **ONLY** for reading implementation details after locating symbols\n- **NEVER** for finding symbol usages (use `GetSymbolReferences_CppTools` instead)\n\n### When to use vscode_listCodeUsages/grep_search\n\n- Finding string literals or comments\n- Searching non-C++ files\n- Pattern matching in configuration files\n- **NEVER** for finding C++ symbol usages\n\n### When to use semantic_search\n\n- Finding code based on conceptual queries\n- Locating relevant files in large codebases\n- Understanding project structure\n- **Then** use C++ tools for precise symbol analysis\n\n---\n\n## Summary\n\n**The golden rule**: When working with C++ code, think \"tool first, manual inspection later.\"\n\n1. **Symbol usages?** → `GetSymbolReferences_CppTools`\n2. **Function calls?** → `GetSymbolCallHierarchy_CppTools`\n3. **Symbol definition?** → `GetSymbolInfo_CppTools`\n\nThese 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.\n\n**Your success metric**: Did I use the right C++ tool for every symbol-related task?\n","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.**","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/cpp-language-service-tools.instructions.md"},"manifest":{}},"content_hash":[66,2,188,236,128,215,147,129,64,114,57,219,104,201,103,221,220,187,162,115,243,33,238,75,200,239,25,248,223,125,245,134],"trust_level":"unsigned","yanked":false}