Roslyn CodeLens — Semantic .NET Intelligence

Response shape

All list-returning tools wrap their results in an envelope:

{
  "items": [...],
  "totalCount": 142,
  "truncated": false,
  "limit": 500,
  "summary": { ... }
}

When truncated is true, items are the top N by the tool's natural sort order (severity-first, worst-first, by-project, etc.) — usually that's what you want. Raise limit only if the truncated tail matters for the task.

Tools that include a summary aggregate:

• get_diagnostics — { error, warning, info, hidden } counts
• find_references, find_callers, find_attribute_usages — { byProject: { name: count } }
• search_symbols, find_reflection_usage — { byKind: {...} }
• find_unused_symbols — { byKind: {...}, filteredOut: { testMethod, testContainer, mcpTool, generated, composition, interop } }
• find_naming_violations — { byRule: {...} }
• get_complexity_metrics — { max, avg, overThreshold }

Single-object tools (get_type_overview, get_symbol_context, apply_code_action, etc.) are unchanged — they return their bespoke shape directly.

Error responses

When a tool can't proceed, the response is isError: true with content carrying a JSON body of { code, message, details? }. Switch on code:

If code: SolutionNotTrusted, the right next step is calling trust_solution after asking the user. Don't catch and retry blindly — the user has to authorize analyzer execution.

Detection

If find_implementations is not available as an MCP tool, this skill is inert — do nothing, no errors.

If it IS available, every rule below applies. No exceptions.

The Iron Law

On a .NET codebase where roslyn-codelens MCP tools are available:

1. Never use Grep, Glob, or Bash grep/rg to locate C# symbols, types, methods, interfaces, references, callers, implementations, or usages.
2. Never run dotnet build, dotnet msbuild, msbuild, or any build command to surface compiler errors, warnings, or analyzer diagnostics.
3. Never manually read a .cs file to "grep in my head" for who uses a symbol, or to check if code compiles.

The semantic tools (find_callers, find_references, find_implementations, search_symbols, get_diagnostics, go_to_definition, etc.) are always more accurate than text search and always faster than a build. There is no tradeoff to weigh.

Violating the letter of these rules is violating the spirit. If you're about to run a command or tool that substitutes for one of these semantic tools, stop.

Red Flags — STOP and Use the MCP Tool

If any of these thoughts cross your mind, stop and switch to the MCP tool:

All of these mean: the MCP tool is the correct tool. Use it.

Rationalizations — and why they're wrong

Pre-Action Checklist

Before calling `Grep` or `Glob` on `.cs` / `.csproj` / `.sln` / `.slnx` / `.cshtml` files:

1. Is the target a C# symbol (type/member/namespace)? → Use search_symbols or find_references.
2. Is the target an attribute? → Use find_attribute_usages.
3. Is the target a reflection pattern? → Use find_reflection_usage.
4. Is it genuinely a string literal, comment, or non-semantic text? → Grep is OK. State why.

Before running `dotnet build` / `msbuild` via Bash:

1. Am I looking for errors, warnings, or analyzer diagnostics? → Use get_diagnostics. Stop.
2. Am I actually trying to produce a binary / run tests / package? → Build is OK. State why.

Before `Read`ing a `.cs` file:

1. Do I just need structure (what's in it, what's defined)? → get_file_overview / get_type_overview.
2. Do I need a specific method's shape? → analyze_method.
3. Do I need the actual source lines to edit? → Read is OK.

When to Use Each Tool

Decision Tree for External Assemblies

I want to...                         Tool / Approach
─────────────────────────────────────────────────────────────────────
Work with types in my source code  → existing tools (unchanged)
Look up an external type by name   → go_to_definition / get_symbol_context /
                                     get_type_overview / get_type_hierarchy
                                     (pass fully-qualified name; returns origin="metadata")
Browse what a package exposes      → inspect_external_assembly
Who in my code uses an ext. type?  → find_references / find_callers / find_implementations
See a method's IL bytecode         → peek_il (pass fully-qualified method name with param types)
Inspect an arbitrary DLL           → add a <ProjectReference> to a throwaway
                                     project, rebuild_solution, then use normally

Understanding a Codebase

• get_project_dependencies — solution architecture, how projects relate.
• get_symbol_context — full context for a type (namespace, base, interfaces, DI deps, public members).
• get_public_api_surface — Enumerate every public/protected type and member declared in production projects; deterministically sorted; suitable for API review or breaking-change baselines. Static analysis; only declared (not inherited) members appear.
• find_breaking_changes — Diff the current public API surface against a baseline (JSON snapshot from get_public_api_surface, or a .dll file). Reports Removed/Added/KindChanged/AccessibilityNarrowed/Widened with Breaking/NonBreaking severity. Static analysis; doesn't currently detect return-type, sealed-ness, or nullable changes.
• get_type_hierarchy — inheritance chains and extension points.
• get_type_overview — one-shot: context + hierarchy + diagnostics (replaces 3 calls).
• get_file_overview — types defined in a file + diagnostics, without reading it.
• analyze_method — signature + callers + outgoing calls, all in one.
• get_overloads — Every overload of a method or constructor (source + metadata) with full parameter detail, modifiers, generic type params, XML doc summary, and location. One call instead of N analyze_method calls.
• get_operators — every +, -, ==, <, conversion, etc. on a type, with kind, signature, source location. Includes synthesized record equality. Covers what get_overloads excludes.
• get_call_graph — Transitive caller/callee graph for a method, depth-bounded with cycle detection. Adjacency-list output. Use when you need depth > 1 (analyze_method is depth=1).

Navigating Code (instead of Grep/Glob)

• go_to_definition — jump to the definition.
• search_symbols — fuzzy symbol lookup.
• find_references — every reference across the solution.

Finding Dependencies and Usage

• find_callers — every call site for a method.
• find_event_subscribers — every += / -= site for an event symbol, with resolved handler name and subscribe/unsubscribe tag. Use for UI-event audits or memory-leak hunts (compare subscribe/unsubscribe pairs).
• find_implementations — all implementors of an interface / extenders of a class.
• find_tests_for_symbol — xUnit/NUnit/MSTest methods that exercise a production symbol; opt-in transitive walk through helpers.
• get_test_summary — Per-project inventory of test methods with framework, attribute kind, [InlineData]/[TestCase]/[DataRow] row count, location, and production symbols referenced. Project → tests direction; complements find_tests_for_symbol (test → production).
• find_uncovered_symbols — Public methods and properties no test transitively reaches (≤ 3 helper hops); sorted by cyclomatic complexity for prioritization. Strict reference-based: an override is not marked covered just because its base or interface declaration is reached — a test calling IFoo.Bar does not cover Foo.Bar.
• generate_test_skeleton — Emit a test-class skeleton (parseable C#) for a method or type. Returns framework, suggested file path, class name, full file contents, and TodoNotes (e.g. constructor dependencies). Stubs cover happy-path Fact, Theory + InlineData for primitive-param methods, Assert.Throws<T> per direct-throw exception type, async detection. Tool returns text; agent decides whether to Write it. Pairs with find_uncovered_symbols (find gap → generate stub).
• get_di_registrations — DI wiring and lifetimes.
• find_reflection_usage — hidden/dynamic coupling (Activator.CreateInstance, MethodInfo.Invoke, assembly scanning).
• get_nuget_dependencies — NuGet packages and versions.
• find_attribute_usages — members decorated with a given attribute.
• find_obsolete_usage — Every [Obsolete] call site grouped by deprecation message and severity. Sharper than find_attribute_usages for migration planning. Source AND metadata obsoletes (NuGet) included.

Diagnostics (instead of `dotnet build`)

• get_diagnostics — compiler errors, warnings, analyzer diagnostics. Replaces dotnet build output.
• get_code_fixes — structured edits for a diagnostic.

#### Trust model for analyzer diagnostics

get_diagnostics defaults to includeAnalyzers=false (compiler diagnostics only). If the user asks for analyzer warnings (StyleCop, Microsoft.CodeAnalysis.Analyzers, CA-prefixed rules, etc.) — OR if you need to call get_code_fixes for an analyzer-rule diagnostic:

1. Call get_diagnostics(includeAnalyzers=true).
2. If the server returns an "untrusted solution" error: ask the user before calling `trust_solution`. Phrase the question to make it clear that analyzer DLLs run as in-process code with the user's privileges. They should only trust solutions they wrote or fully vetted.
3. Prefer scope="session" for one-off reviews. Use scope="persistent" only when the user confirms they regularly use this solution. Use scope="addRoot" to trust an entire directory tree (e.g., c:\projects\).
4. Use list_trusted_paths to inspect current state when the user asks "is X trusted?". Use revoke_trust to drop entries.

Solutions passed on the CLI at server startup are auto-trusted in session scope — get_diagnostics(includeAnalyzers=true) against them works without an extra prompt.

• get_code_actions — all refactorings/fixes at a position (with optional range).
• apply_code_action — execute a refactoring by title. Preview mode by default.
• analyze_data_flow — variable lifecycle over a statement range (declared/read/written/captured/flows-in/out).
• analyze_control_flow — reachability, returns, unreachable paths.

Code generation is in `apply_code_action` — do NOT look for dedicated generation tools. Use get_code_actions to find the title, then apply_code_action:

• Implement missing interface/abstract members → "Implement abstract members" / "Implement interface"
• Generate constructor from fields → "Generate constructor"
• Add null checks → "Add null checks for all parameters"
• Generate Equals/GetHashCode → "Generate Equals and GetHashCode"
• Encapsulate field → "Encapsulate field"
• Extract method → "Extract method"
• Inline variable → "Inline variable"

Code Quality Analysis

• find_unused_symbols — dead code (reference-based). Auto-filters test methods, MCP tool entry points, source-generator output, MEF-composed services, and interop-laid-out fields; counts surface in summary.filteredOut.
• get_complexity_metrics — cyclomatic complexity per method.
• find_naming_violations — .NET naming conventions.
• find_async_violations — Detects sync-over-async (.Result/.Wait()/GetAwaiter().GetResult()), async void outside event handlers, missing awaits in async methods, and fire-and-forget tasks. Severity error/warning per violation. Static analysis; no runtime data.
• find_disposable_misuse — Detects IDisposable/IAsyncDisposable instances not wrapped in using/await using/returned/assigned-to-field-or-out-parameter (warning), and bare-expression-statement discards of a disposable creator/factory (error). Static analysis; no runtime data.
• find_large_classes — oversized types.
• find_god_objects — Types crossing all 3 size thresholds (lines/members/fields) AND a coupling threshold (incoming or outgoing namespace count). Sharper than raw size: a large but isolated class isn't flagged; a 200-line class with 15 callers across many namespaces is.
• find_circular_dependencies — project/namespace cycles.
• get_project_health — Composite audit: complexity, large classes, naming, unused, reflection, async violations, disposable misuse — counts + top-N hotspots per dimension, per project. Use when you'd otherwise call 7 separate audit tools.

Source Generators

• get_source_generators — list generators and their outputs.
• get_generated_code — inspect generated source (filter by generator or file path).

Working with External Assemblies (Closed-Source / NuGet)

External symbols have origin.kind = "metadata" in tool results. Supply fully-qualified names (e.g. Microsoft.Extensions.DependencyInjection.IServiceCollection) to the Tier-1 tools below — they fall back to metadata lookup automatically when no source match is found.

• inspect_external_assembly — browse a referenced assembly's public API:
• mode="summary" → namespace tree + type counts (start here to orient yourself)
• mode="namespace" → full type + member listing for one namespace
• peek_il — read ilasm-style IL for a single method in a referenced assembly:
• Input: fully-qualified method name with parameter types (e.g. Namespace.Type.Method(ParamType1, ParamType2))
• For constructors: use ..ctor notation (e.g. Namespace.Type..ctor(ParamType))
• Output: raw IL instructions (IL_0000: ldarg.0, etc.) — not decompiled C#
• When to use: after find_callers / get_symbol_context identifies an interesting external method and you want to understand its implementation

Worked example — drill into a NuGet package:

inspect_external_assembly(assemblyName: "Microsoft.Extensions.DependencyInjection.Abstractions", mode: "summary")
→ shows NamespaceTree with Microsoft.Extensions.DependencyInjection (15 types)

inspect_external_assembly(assemblyName: "Microsoft.Extensions.DependencyInjection.Abstractions",
    mode: "namespace", namespaceFilter: "Microsoft.Extensions.DependencyInjection")
→ returns IServiceCollection, ServiceDescriptor, ServiceLifetime, etc. with members and XML doc summaries

To find where your code uses an external symbol: Use find_references / find_callers / find_implementations with the fully-qualified external symbol name. Results will be source locations in your codebase.

To find all source files using `IServiceCollection`:

find_references("Microsoft.Extensions.DependencyInjection.IServiceCollection")
→ returns source locations (all origin.kind="source") where your code references IServiceCollection

find_callers("Microsoft.Extensions.DependencyInjection.ServiceCollectionServiceExtensions.AddSingleton")
→ returns source call sites for AddSingleton (pass the extension class + method name)

To read the raw IL of an external method: Use peek_il with the fully-qualified method name including parameter types:

peek_il("Microsoft.Extensions.DependencyInjection.ServiceDescriptor..ctor(System.Type, System.Type, Microsoft.Extensions.DependencyInjection.ServiceLifetime)")
→ returns ilasm-style IL text, assembly name, and version

Limitations: abstract methods, interface instance members, and properties-as-whole (target the getter/setter accessor instead) are not supported.

Solution Management

• list_solutions — loaded solutions, which is active. Includes a SkippedProjects array per solution: projects MSBuildWorkspace could not load (legacy non-SDK-style csproj, missing files), with Kind and Reason.
• set_active_solution — switch active solution by partial name.
• load_solution — load a .sln/.slnx at runtime. Returns a confirmation; when projects were skipped, the message summarises them and points to list_solutions for per-project reasons. For very large solutions (hundreds of projects) that take minutes to open, pass background: true to get a taskId back immediately and poll get_task_status instead of blocking — the new solution becomes active only once that task succeeds, so other tools keep working against the current solution meanwhile.
• unload_solution — free memory.
• rebuild_solution — full reload (after Directory.Build.props changes, new analyzers/packages, or stale diagnostics).

Legacy project handling: when a solution contains non-SDK-style projects (<Project ToolsVersion="..." xmlns=".../msbuild/2003">, typically older .NET Framework projects), the server pre-filters them out before MSBuild sees them. Those projects appear in SkippedProjects with Kind: "Legacy". The SDK-style projects in the same solution load normally and remain fully queryable — partial load, not all-or-nothing. If a tool returns "no results" for what should be a legacy project, check list_solutions first.

Planning a Change — standard order

1. get_type_overview — context + hierarchy + diagnostics.
2. analyze_change_impact — blast radius (files, projects, call sites).
3. find_references / find_callers / find_implementations — detailed dependency breakdown.
4. get_project_dependencies — architectural position.
5. get_di_registrations — wiring.
6. find_reflection_usage — dynamic coupling.
7. find_attribute_usages — attribute-driven behavior.
8. get_diagnostics — existing issues.
9. get_code_fixes / get_code_actions → apply_code_action — auto-fixes and refactorings.
10. find_unused_symbols — dead code to delete instead of refactor.
11. get_complexity_metrics — complexity hotspots.

Reference concrete types, interfaces, and call sites in your analysis. Not "the services that implement this" but "These 3 classes implement `IUserService`: `UserService`, `CachedUserService`, `AdminUserService`."

Tool Quick Reference

Legitimate Grep / Build Exceptions

Grep is the correct tool for:

• Non-C# files (.json, .yaml, .md, .razor template text, shell scripts).
• String literals and comments inside C# code.
• Text that isn't a symbol (log messages, error strings, TODOs).

dotnet build is the correct command for:

• Actually producing a binary.
• Running tests (dotnet test) — not covered by this skill.
• Packaging / publishing.

State the reason when you take the exception. If you're about to type a Grep/Glob/build command and can't state the reason out loud, you're rationalizing — use the MCP tool.

Metadata Support by Tool