Reading and navigating C# with dotnet-toolkit

Every question below is answered by a Roslyn-backed MCP tool that reads the compiler's own model. Grep, Glob, find, cat, sed and whole-file Read on a .cs file are wrong here for finding things, not just slower — they cannot see interface, virtual or delegate dispatch, count comment and string matches as real hits, silently under-report when output is truncated, and hand back one fragment of a partial class with no signal that the rest exists. Reading the text once it is located is a different matter: no tool here returns source. get_symbol answers where (declarationSites, doc comment included), and a ranged Read over that range fetches the text — that is the intended pair, and a ranged read draws no hook note. A PreToolUse hook adds an advisory when Read or a shell read takes a whole compiled .cs file, but does not block it — Grep/Glob are watched by no hook at all. The router below, not hook enforcement, is what keeps you on the right tool.

Tool names carry a host-dependent prefix. In Claude Code they are mcp__plugin_dotnet-toolkit_dotnet__<tool>, because the plugin qualifies the server it ships. Codex registers the same server under the bare name dotnet and namespaces by that instead, so the prefix differs there. Every fully-qualified name below is written in the Claude Code form.

Resolve the prefix once per session rather than assuming it. Run ToolSearch("select:mcp__plugin_dotnet-toolkit_dotnet__workspace_status"); if that returns nothing, search for the bare tool name (ToolSearch("workspace_status")) and read the prefix off whatever comes back, then apply that same prefix to every name in this skill. One probe settles it for the whole session. Do not guess a prefix and do not fall back to Grep/Read because a qualified name missed — the tools are there under a different label, and the fallback is the failure this skill exists to prevent.

Step 0 — call workspace_status before any read

First MCP call of the session, always. It is free, takes no arguments, records no telemetry, and gives you two things nothing else can:

1. Readiness. Until the workspace is loaded, semantic tools answer from the syntax tier or refuse outright. A zero-hit from get_references, get_call_hierarchy, get_call_slice, get_type_hierarchy or get_semantic_diff against a cold workspace is workspace state, not absence — never report it as "nothing uses this".

2. pluginRoot. The plugin's install directory, and the only supported way to reach a file that ships with the plugin. Join it yourself:

   • a tool manual → <pluginRoot>/docs/tools/<tool>.md
   • a coding standard → <pluginRoot>/standards/<name>.md

   Never write ${CLAUDE_PLUGIN_ROOT} into a path. The harness substitutes it into .mcp.json args, hook commands and skill content, but not into a rule or an agent definition, so it stays literal and the read fails. Read the joined path — the read guards only ever note a .cs file.

Re-call it whenever a response comes back stale or degraded (see Workspace readiness below).

Step 1 — load the tool by its exact name

Schemas are deferred: a tool must pass through ToolSearch once per session before it can be called.

Pick the tool from the tables below, then load it by exact name:

ToolSearch("select:mcp__plugin_dotnet-toolkit_dotnet__get_references")

Never describe the task to ToolSearch and let it rank candidates. The mechanism is lexical (regex or BM25 over tool names, descriptions and argument descriptions), not semantic. Measured here: 11 of the then 18 tools failed to appear in the top 5 for a natural-phrasing query — "who calls this method" never surfaced get_references at all. The tables below pick the tool; ToolSearch only fetches it.

The schema is then enough for an ordinary call. Reach for a manual only for an advanced selector, an unfamiliar response field, or error recovery.

The tools

search_index — find symbols when you don't know the exact name

Answers to:

• Where is the class/interface/method/property/field called X?
• What symbols exist matching these several terms at once?
• Which types implement IFoo, or live under this folder?
• Which symbols are public, static, abstract, async, extension methods, IDisposable?
• Which symbols have (or lack) an XML <summary>, <returns>, <remarks>?
• How is the codebase laid out by namespace or by file?
• Roughly what will fetching this symbol cost me?
• Does anything actually use this — is it dead code?
• Did any of my search terms find nothing at all?

One call, every term. Terms are OR-ed and ranked together: search_index(query: "fee ledger TryBuy TrySell") answers for all four in one round trip. Each term gets only a shallow floor share of limit, so always read termsWithNoHits — a term the result never covered is named there, and an absent term is never evidence of an absent symbol.

query matches identifier text, not structure. query: "class", "partial class" or "nested" searches for a symbol literally named that — it is never how you ask "list every class" or "list every partial/nested type", and returns nothing when this repo has no symbol named class. "Is a class" is the kinds filter; "is partial/static/public/…" is modifiers; "is nested" has no filter at all — read it off shape's N count. If you don't yet know a real identifier or domain noun to search for, Read this project's README.md (or CLAUDE.md if there is no README.md) before the first search_index call — both are plain Markdown, not .cs, so this skill's tools don't apply to them.

A hit is one symbol, not one declaration. A type declared partial across several files collapses to a single ranked row, whose file names only the fragment that ranked. parts: N (with a partsHint) appears when N > 1 and says so; absent means one file. Never read a ranked page as an enumeration of declaration sites — get_symbol's declarationSites is the call that enumerates them, and on a 13-file partial a benchmarked MCP route read the hits instead and answered 5.

A hit's lines (@from-to) is the signature span only — it excludes a leading /// doc comment, so it is the line to quote for "where is this", not the range to Read for the whole declaration. get_symbol's declarationSites is the range to read.

Names only. The index holds identifiers and doc summaries, not bodies: a string literal, a log message, a comment or a local variable is not findable here. That one question is a Grep, and the only one on C# where it is the right tool. A type you can only describe is often that question too: <summary> text is indexed, <remarks> and body comments are not, so when the phrase that discriminates it ("full pivoting", "re-runs elimination") lives in prose, one Grep over the tree lands on the doc comment where two name-guessing searches return nothing — measured on FluidScript (2026-09-20), where the raw route won that question outright. Grep the phrase, then get_symbol on the type it sits above.

include picks each hit's columns, comma-separated, and replaces the default set exactly as get_symbol's include does. Default: shape,refs,modifiers. Also available: summary (a hasSummary bool) and summary:full (the text, capped at 160 chars). Commas, never hyphens.

All three columns are terse codes, each with its legend stated once per response:

Uppercase-with-digits is shape/refs; lowercase-without is modifiers, so the columns never blur together even though both reuse letters.

refs answers "is this used anywhere" without a second call, in one batched lookup for the whole page. Read its zeroes and its silences precisely:

• A digit is a measured fact. R0 means nothing calls this — the dead-code answer the column exists to give. A named type gets I instead of R, because call edges bind to members.
• A missing letter means that fact cannot apply to this symbol's kind, or is zero and not worth three bytes. Only R (on a member) and I (on a type) are emitted at zero.
• A missing whole column is "not measured", never "zero". The project's edges were never indexed — typically because it failed to load in MSBuild, which once hid a method that had 5 callers. refsHint says so when it happens, and reading that silence as "unused" is how live code gets deleted.
• R counts calls written against the symbol itself. One made through an interface is recorded against the interface member, so a method reached only by dispatch can legitimately read R0. When dispatch is the question, ask get_references or get_symbol's referenceCounts — both expand to the interface members a symbol implements.

A describe-the-operation lookup compares summaries, never takes the top hit. When the question names what a type does rather than what it is called, ask with include: "shape,refs,modifiers,summary:full" so every hit's summary comes back in the same call, and read the top few before choosing. Two probes issued near-identical queries on FluidScript (2026-09-20); the one that took the top-ranked hit named the consumer of the thing asked for, the one that read the runner-up's summary got it. The verb in a summary ("derives", "computes", "builds") is what settles it; ranking is by name tokens and cannot.

Read shape before deciding the next call. A type with a large M wants get_symbol(include: "members"), never a whole-type Read. A member with a large L wants get_symbol(include: "bodyOutline") to map it, then a Read of the one region. Anything small wants get_symbol for declarationSites and one Read of that range.

Manual: <pluginRoot>/docs/tools/search_index.md

get_symbol — locate a symbol you can name

Answers to:

• Where exactly is this symbol declared — every file and line range, partials included?
• What XML docs, attributes, members, interfaces and base type does it have?
• How many callers, tests, implementations and overrides does it have?
• What is its control-flow structure, without reading the whole body?
• Is the name I used ambiguous, or misspelled?
• Is expanding to its references worth it?

It returns no source text. declarationSites carries file, startLine (where a leading /// doc comment begins), signatureLine (where the declaration itself begins; present only when it differs) and endLine (the closing brace), one entry per part of a partial. The text is one ranged read away:

Read(file, offset: startLine, limit: endLine - startLine + 1)

That pair — get_symbol to locate, Read of that range to fetch — is the whole reading path. It costs less than a whole-file Read on anything but a tiny file, misses no part of a partial, and the ranged read draws no hook note. Do not Read a whole file to find a symbol you could have named. Read startLine..endLine once — it already includes the /// block. Reading from signatureLine and then a second time from startLine "to get the doc comment" is two reads for one span; both MCP routes on PandaAI (2026-09-20) paid it. And a range past ~100 lines is a sign to outline first: get_symbol(include: "bodyOutline") maps a long member's landmarks so the read is the one region, not three 150-line slices of it — the MCP ceiling on PandaAI lost ~5k tokens to exactly that, on a question the outline would have settled in one slice.

Report a location from signatureLine, not startLine. signatureLine comes first in the row and is where the declaration begins, matching what search_index reports; startLine is the read offset and takes in the doc comment. Answering "declared at line 3" when the class keyword is on line 7 is the mistake it exists to prevent — on FluidScript (2026-09-20) it was 42 lines, the length of the doc comment.

include is a plain comma list of component names that replaces the default (xmlDoc, referenceCounts):

include: "members"                      a type's surface — navigate by member list, not by reading the type
include: "bodyOutline"                  landmarks in a long member, then Read one region
include: "members,baseType,interfaces"  a type's shape from outside
include: "mechanicalFacts"              does it throw / await / lock / write, without reading it

members is capped at 40, with totalMembers/truncated past the cap.

A single-symbol lookup always carries xmlDoc, whatever include says — a batch keeps include literal. The doc comment is the one line you are about to act on: an <remarks> saying a method exists to satisfy an analyzer rule, or is not thread-safe, or is obsolete. Read it before deciding anything about the symbol. On FluidScript (2026-09-20) every route declared a method "safe to delete" on the strength of zero references, while its own remarks said the build depends on it. Zero references answers "is this called", never "is this needed".

Manual: <pluginRoot>/docs/tools/get_symbol.md

get_references — who calls it, and from where

Answers to:

• Who calls this method, and at which file and line?
• What uses this type — as a field, parameter, return type, or construction site?
• What implements this interface, or overrides this virtual?
• How many text-only matches would a grep have given me falsely?
• Are any of these use sites tests?
• Are there more references than came back, and how do I page to them?
• Is a 0-caller result actually safe to treat as dead code?

direction is callers (default) | implementations | overrides. Each item carries a symbolId, a displayString, and sites — {file, line, snippet}, one row per file+line. On a named type there are no call sites, so callers returns the members that reference it.

totalItems counts referencing symbols; totalSites counts the sites themselves and is present only when the two differ. Asked "how many call sites", report totalSites — hand-tallying the rows across items is how a benchmarked route delivered 18 of the 19 sites its own response contained.

A 0-caller result on a known reflection entry point is not evidence it is unused. entryPointHint (present only in that exact shape) says so directly — a [Fact]/[Theory]/[Test]/[TestMethod] method, an [McpServerTool]/[McpServerPrompt]/[McpServerResource] handler, an ASP.NET routing attribute ([HttpGet], [Route], …), [JsonConverter], [ModuleInitializer], or a static Main is invoked by its own framework's reflection scan or routing table, which leaves no call-site edge for this or any static reference search to find. Two separate blind benchmarks of this tool caught this exact shape producing a confidently wrong "safe to delete" verdict — first on a [Fact] method, later on an [McpServerTool] one on an unrelated repo — before the hint generalized past tests; don't re-derive that caveat from memory when the field already states it. For a routed action the hint also says where the callers are — outside the compilation — and that is a Grep of the route template over the client code (ClientApp/, a TypeScript tree, HttpClient callers) before any "safe to delete" verdict. On PandaAI (2026-09-20) the MCP route stopped at the hint with a correct "no" and no caller; the raw route's whole-tree grep found the React consumer. The compiler's view ends at the process boundary, and this is the one delete-safety question where that boundary is crossed.

Do not read a large dispatchKind: virtual count as a large real fan-in, and do not report an indirect row as a caller of this member. Roslyn cascades: a call written against a base or interface declaration is reported as a caller of everything that overrides or implements it. Those rows are marked indirect: true and carry via — the member the call actually binds to — and the envelope splits directItems from indirectItems and says so once in dispatchNote. Asked "where is this called with the receiver typed as Pipe", the answer is the rows without indirect, and nothing else needs reading; on FluidScript (2026-09-20) a route reported all eight rows where three were right. indirectItems means "could land here", not "does".

Check targetDisplayString when a count surprises you. A bare-name or suffix symbol handle can bind to something you never meant, and the wrong answer looks exactly as authoritative as the right one. That field names what actually resolved; targetSymbolId is a hash and confirms nothing on sight.

An item's symbolId is a fetch target; the text at a site is a Read around sites[].line, or a get_symbol on the item for its whole declaration span — and only for the sites you will change.

Manual: <pluginRoot>/docs/tools/get_references.md

get_call_hierarchy — the multi-level call tree, and blast radius

Answers to:

• Who eventually calls this, up to the entry points?
• What does this eventually call, several hops down?
• If I change this, how far does the change ripple?
• How many distinct symbols does it reach, per depth?
• Was the tree truncated, and where?
• Is there recursion in this path?

direction: "callers"|"callees", maxDepth (default 3). includeTree: false returns only blastRadius — the cheapest possible answer to "how much does changing this ripple".

Never for "how does A reach B". When both ends are named, that is get_call_slice, and the difference is not small: a callees tree from a well-connected root is the most expensive response this server produces — on FluidScript (2026-09-20) two independent probes each paid 13–18k tokens for a three-hop path inside one file that get_call_slice answers in a few hundred. The hierarchy tool is for an open-ended question with one known end.

Manual: <pluginRoot>/docs/tools/get_call_hierarchy.md

get_call_slice — is there a path from X to Y

Answers to:

• Does control flow reach from this function to that one?
• What is the shortest path between them, and through what?
• If there is no path, how close does each end get?

Both endpoints must already be named. Use it instead of walking the graph with repeated get_references calls.

Manual: <pluginRoot>/docs/tools/get_call_slice.md

get_scope — what is callable at this exact line

Answers to:

• What can I call at this file/line/column?
• Which extension methods apply to this receiver?
• Does a helper for this already exist before I write one?
• What is in scope when I don't yet know the receiver's type?
• Which members are inherited rather than declared here?

Grep cannot answer this at all: an extension method shares no text with its call site. Different from get_symbol(include: "members"), which is a type's static declared list with no position involved.

Manual: <pluginRoot>/docs/tools/get_scope.md

get_type_hierarchy — the full base chain and every implementer

Answers to:

• What is this type's complete base chain, up to object?
• Which interfaces does it implement, directly and inherited?
• Which types derive from it or implement it?

One hop further than get_symbol's single containingType/baseType. Don't guess a hierarchy from a one-hop fetch.

A derived entry carries isAbstract/isSealed when true, so "which of these are concrete" is answered from the same call — the derived list mixes abstract intermediates in with concrete leaves, and reporting all of them as implementers is a measured wrong answer, not a rounding error.

Manual: <pluginRoot>/docs/tools/get_type_hierarchy.md

get_project_graph — which project references which

Answers to:

• What does this project reference, and what references it?
• What is the solution's whole project dependency graph?

Use it instead of opening every .csproj.

Manual: <pluginRoot>/docs/tools/get_project_graph.md

detect_circular_dependencies — reference loops

Answers to:

• Is there a real dependency cycle between projects?
• Which projects form it?

Manual: <pluginRoot>/docs/tools/detect_circular_dependencies.md

get_semantic_diff — what a commit or branch actually changed

Answers to:

• Which symbols were added, removed or changed between two refs?
• Which version layers moved — declaration, body, or both?
• What is the API impact of this change?
• Was this commit formatting-only?

Use it instead of reading a textual diff and inferring. Formatting- and comment-only commits correctly report no change.

Manual: <pluginRoot>/docs/tools/get_semantic_diff.md

get_retrieval_metrics — where the tokens went

Answers to:

• How many tokens has this session spent on retrieval?
• Which tool, symbol or task cost the most?
• What did one specific call cost? (snapshot groupBy: "tool" either side and subtract)

It reports this server process and nothing else, always — the raw telemetry is cleared when the server starts and again when it stops, and there is no argument that reads another session. A number here is this session's, never a month of accumulated history.

Pass a taskId on the calls you want to isolate — it is the only thing separating concurrent callers, since every agent talking to this server process shares one ambient session id.

Manual: <pluginRoot>/docs/tools/get_retrieval_metrics.md

workspace_status, reload_workspace, ping, set_output_format

Answers to:

• Is the workspace ready, is indexing done, where is pluginRoot? → workspace_status
• Which projects failed to load, and why? → workspace_status
• A tool just failed, or results look frozen at an older revision? → workspace_status. It prints knowledgeCache: when the SQLite cache is damaged (symbol search and reference counts are then disabled for the session, and the cache is rebuilt on the next server start), and msbuild: when no installed SDK satisfies the repo's global.json — the state that otherwise reaches you as an unresolved Microsoft.Build.Framework. Both lines are absent when nothing is wrong.
• I pulled/checked out/rebased — how do I refresh? → reload_workspace(scope: "all"). An Edit/Write needs nothing: the refresh-cs-files hook re-indexes what was written, and the index: line says symbols refreshed Ns ago and how many files are still queued
• Is the server answering at all? → ping
• How do I get plain JSON instead of TOON? → set_output_format(format: "compact"|"json")

Manual (all four): <pluginRoot>/docs/tools/server.md

The cheap-route table

Each row is a route actually observed being taken, and the cheaper route that answers the identical question. This table is why this skill exists: these findings used to live only inside individual tool manuals, which are not loaded unless something already went looking — so the anti-pattern was committed before the note that prevents it was ever read.

Workspace readiness — limitedBy

limitedBy names what the answer could not draw on. It applies to every retrieval tool.

• absent — fully informed. Silence is the healthy case.
• index_only — the syntax tier answered. Reference counts and semantic resolution are unavailable, not zero.
• stale — the file changed on disk since the workspace read it. The next sweep (within a couple of seconds) clears it by itself; re-call after that, since line spans will have moved. Never anchor an edit on a stale response's lines.
• degraded — projects failed to load. Results may be silently wrong, not merely thin. Call workspace_status, fix the build, then reload_workspace. Never report a finding from a degraded workspace without saying so.

get_references needs live semantics and returns error: "workspace_loading" until ready. After a large git operation, call reload_workspace; after an ordinary edit, nothing — the refresh hook and the sweep keep the index current.

Reading responses

Responses are TOON by default — the same field names as the JSON documented in each tool manual, more compact. set_output_format(format: "compact"|"json") switches for the session.

Switch formats the moment TOON is costing you accuracy. TOON is the default because it is the cheapest encoding of the identical data, not because reading it is a requirement — every field name is the one the manual documents either way. A response you parse tentatively is the expensive outcome, because the next call is built on a field you guessed at:

Re-issuing an identical call in the same format returns identical bytes. If a response disappointed you, change the question, the arguments, or the format — never repeat it unchanged.

Absent is not zero. An absent field carries no information: an absent tests means "not computed", not "no tests". A null is dropped rather than written as "field":null, so check for the key's absence, not its value. The one deliberate exception is search_index's shape column, whose legend says so: an absent letter means zero or not-applicable, never "not computed".

Every tool that records telemetry takes an optional taskId. No tool takes a sessionId.

When to hand off

• The set of symbols the task touches isn't known yet → invoke dotnet-explore instead of fanning out search_index/get_references here. It spends the wide responses in its own context and hands back symbolIds, use sites and blast radius. Skip it when the symbol is already known.
• About to change a .cs file → invoke dotnet-write. It owns the locate-read-edit-build loop, the standards step, and how the index follows your edits.
• Judging code quality → invoke dotnet-review. Never review C# inline.

Non-C# files (.csproj, .json, .md, .cmd) are ordinary Read/Grep territory — this skill does not apply to them.