Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds genuine behavior beyond that: scope omission falls back to the loaded solution, and the result set is truncated with findings.hasMore signalling incompleteness. It stops short of describing ordering or how truncation interacts with the limit, so not quite a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each load-bearing: rule set, when-to-use plus alternative, default scope, and truncation caveat. The most decisive constraint (the exact rule set) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return shape needn't be explained, and the description still flags the one output field that matters for correctness (findings.hasMore). Together with the scope fallback and the sibling routing, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds one piece of meaning beyond the schema — that an omitted scope searches the whole loaded solution — and restates the 50 default already present in the schema, which earns no credit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Reports) and a precisely bounded resource: only bundled AsyncFixer01–AsyncFixer06 plus compiler warning CS4014. It explicitly contrasts itself with get-diagnostics, so an agent can pick the right tool without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the when ('focused async/await review'), a non-obvious edge case ('including bundled rules when the project does not reference AsyncFixer'), and names the alternative ('use get-diagnostics for general compiler and project analyser findings'). Selection is fully determined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds real behavior: strict selection validation that causes rejection, the requirement to echo expectedSnapshot for concurrency correctness, and independent truncation of exits and returns at 100 with hasMore flags to check. That is more than the annotations convey, though it does not describe error surfacing when the snapshot is stale.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then alternatives, then the validation constraint, then snapshot and limits — a sensible ordering with no filler. It is dense and slightly packed (multiple constraints per sentence), but every sentence carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, nested-schema, read-only analysis tool with an output schema, the description covers what an agent needs before calling: scope semantics, sibling routing, the exact-match precondition, snapshot echoing, and truncation behavior. Return-value shape is correctly left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents the exact-statement requirement, the expectedSnapshot echo, and the 100-item defaults for exitsLimit/returnsLimit, so the description mostly restates structured data. The only genuine addition is pointing at the exits.hasMore/returns.hasMore output flags, which is output-side rather than parameter meaning — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Analyses entry and exit reachability, exit points and return statements') plus the exact scope ('an exact complete statement or contiguous sibling statements in one executable body'). It explicitly distinguishes itself from get-control-flow-graph (enclosing graph) and analyze-data-flow (variable flow), so an agent can pick it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('use this to understand a selected region') and names two alternatives with the conditions that select them. It also states a hard precondition — the selection must match statement spans exactly and a caret or partial statement is rejected — which is exactly the kind of guidance that prevents wasted calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavior: each variable category is independently truncated at 50 symbols by default with a hasMore flag the caller must check, and the request must echo a current expectedSnapshot. These are concurrency and completeness contracts the agent could not infer from the structured fields. It stops short of describing what happens on snapshot mismatch or what error surfaces look like, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the capability, then routing, then the operational caveats. Dense but every clause carries information (scope, alternatives, snapshot echo, category truncation). The opening sentence is long and jargon-heavy, but trimming it would lose the scope definition that distinguishes it from siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description correctly spends its words on when to call it, which sibling to prefer, the snapshot precondition, and the truncation caveat. Complete enough to invoke correctly; only error/failure behavior is unaddressed, which is a minor gap for a read-only analysis tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: location must be an exact expression, complete statement, or contiguous sibling statement range, and expectedSnapshot must be the one returned with the state used to build the request. It also flags the default per-category cap that governs symbolsPerCategoryLimit, which the schema documents only as a bare maximum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (returns) and a precisely bounded resource: Roslyn variable sets for declarations, reads, writes, captures and data flowing in/out of an exact expression, statement, or contiguous sibling statements in one executable body. It also names the two nearest siblings (get-operation-tree, analyze-control-flow) with their distinct scopes, so an agent can separate them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('use this when planning to extract or move selected code') and explicitly routes two alternatives to their own purposes ('get-operation-tree for semantic operation structure', 'analyze-control-flow for region reachability and exits'). Both when-to-use and when-to-use-something-else are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral detail: which patterns are recognised (direct or finally-block Dispose/DisposeAsync), what is skipped (using declarations), the heuristic/advisory nature of the results, the default scope fallback, and a 50-finding cap with findings.hasMore. The only gap is how findings should be interpreted beyond 'verify manually,' but that is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior and no filler sentences; each clause carries information (scope, exclusions, limits, alternative tool). It is dense to the point of being slightly packed, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return shape, and it still calls out findings.hasMore so the agent knows to paginate. Combined with the exclusions, advisory framing, scope fallback, and sibling routing, an agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; however the description adds semantics not obvious from the schema, namely that an omitted scope means the loaded solution is searched, and that findingsLimit defaults to 50 with hasMore signalling truncation. It does not explain the scope kind discriminator beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Heuristically flags local declarations of IDisposable or IAsyncDisposable values that lack a recognised disposal pattern.' It also distinguishes itself from get-diagnostics by framing itself as a heuristic local-declaration scan rather than configured compiler/analyser rules.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this for advisory resource-handling review; verify ownership transfers and control flow before acting,' and routes the agent elsewhere: 'use get-diagnostics for configured compiler and analyser rules.' It also names what is out of scope (using declarations, non-local declarations), which is genuine when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the readOnly/idempotent/non-destructive profile, and the description still adds real behavior: CS86-only filtering, findings depend on compiler settings, a default 50-cap with zero meaning empty, the findings.hasMore signal, and the requirement to echo expectedSnapshot. The only gap is what happens if the snapshot mismatches (error vs. silent refresh), which is left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five compact sentences, each load-bearing: purpose, alternatives, location precedence, default scope, then limits/pagination. The distinguishing filter and sibling routing are front-loaded with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, five-optional-parameter query tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is filtered, how scope vs. location resolve, the default limit, and how to detect truncation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds precedence semantics not obvious from the schema: a supplied location overrides scope and keeps only diagnostics intersecting its resolved span, and an omitted location searches the selected scope or the loaded solution. It does not elaborate on span/selection construction, but the schema covers that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Reports compiler diagnostics whose IDs begin with CS86 for focused nullable analysis" gives a specific verb, resource, and a stated filter (CS86 codes) that separates it from the generic diagnostics siblings. An agent can tell it apart from get-diagnostics without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent elsewhere: get-diagnostics for other compiler/analyser findings and get-document-options for project-level nullable context. The location-vs-scope precedence rule is also stated, leaving little to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context on top: the tool reads the loaded workspace without executing code, nested lambda/local-function bodies are skipped, and results are bounded by calleesLimit with callees.hasMore signaling truncation. It also clarifies what is NOT returned (call sites, runtime dispatch targets).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling contrast, and the trailing sentences each carry new information about depth, truncation, and output shape. Slight redundancy with the schema's own defaults (maxDepth 3, calleesLimit 100) and the 'provide exactly one of' constraint costs it a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with nested objects, it covers input selection, depth traversal semantics, truncation behavior, and output shape. Since an output schema exists, no further return-value detail is required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage the baseline is 3, but the description adds real semantics: direct calls sit at depth 1, maxDepth defaults to 3, calleesLimit defaults to 100, and hasMore indicates truncation within the requested depth. It restates a couple of schema defaults, which keeps it just short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Finds distinct method and constructor targets invoked by...') and scopes the input to an executable symbol or region. It explicitly distinguishes itself from the sibling find-callers, so an agent can choose between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this for outgoing calls; use find-callers for incoming call sites' gives an explicit alternative and the condition that selects it. It also explains the direct-vs-indirect default and that exactly one of symbol or location must be supplied, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds important truncation semantics: default limits of 100 callers and 100 call sites per caller, independent limits, and the need to check callers.hasMore and callSites.hasMore before treating results as complete. It does not discuss performance or snapshot consistency, but it covers the main behavioral risk of incomplete results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and alternatives, then moves to scope behavior, limits, and completeness checks. Every sentence contributes operational guidance with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema and the presence of an output schema, the description supplies what structured fields do not: sibling differentiation, scope fallback, independent pagination limits, and how to detect incomplete results via hasMore flags. Nothing essential for correct invocation appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters in detail. The description reinforces the scope fallback and the independent caller/call-site limits, but most of that information is already present in the schema descriptions, so it adds only modest value beyond structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it finds callers of a resolved symbol and groups source call sites by calling symbol. It also explicitly distinguishes itself from find-references and find-callees, so an agent can select it without opening sibling schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing guidance: use this to trace incoming calls, use find-references for general source usages, and use find-callees for calls made by a selected member. It also clarifies that omitted scope searches the loaded solution, removing a common ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the read-only, idempotent, non-destructive profile, yet the description adds real behavioral detail: hard analysis budgets that reject with AnalysisLimitExceeded rather than returning partial results, and the shape of the return (bounded strongly-connected node groups, not ordered paths). Minor gap is that it does not state whether results are cached or how cost scales before the limits hit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling alternative, then layers in granularity semantics, return shape, and limit behavior. Dense but each sentence carries distinct information; the budget sentence could be tightened slightly but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to enumerate return fields, yet it still tells the agent how to page through results (cycles.hasMore) and why it may get a hard failure. For a 6-param analysis tool with optional params, this is complete enough to invoke correctly on the first try.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: 'Namespace groups source dependencies and Project uses direct project references' explains what the enum values actually do, and it clarifies that a document scope resolves to its containing project under Project granularity. It also ties cyclesLimit to cycles.hasMore.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Finds mutually dependent groups in a static dependency graph'), including the default scope when the parameter is omitted. It explicitly separates itself from get-dependency-graph, so an agent can choose between them without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the sibling tool and the condition that selects each: use this for circular coupling, use get-dependency-graph for individual edges. It also tells the agent how to recover from a rejected query (narrow scope or raise the budget).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real operational context beyond them: default of three inheritance levels, 100 returned types, and the fact that deeper types are silently excluded past maxDepth. The one addition an agent would want is how the result set is ordered, which is left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each carrying distinct information: purpose, sibling routing, interface case, scope/defaults, truncation. Purpose and routing are front-loaded with no preamble or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only query tool with a full output schema, the description covers selection, defaults, truncation signalling (derivedTypes.hasMore) and scope fallback — everything needed to call it correctly. Return-value detail is properly delegated to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still earns above baseline by explaining the interaction between maxDepth and derivedTypesLimit (truncation within depth, deeper types excluded) and the scope-omitted default. It does not, however, tell the agent that derivedTypesLimit=0 yields no results beyond what the schema note already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Finds source types derived from a resolved named type') plus the distinguishing output trait (inheritance distance). It also names the two siblings it is not (get-type-hierarchy, find-implementations), so the agent can select without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use this for descendants, get-type-hierarchy when base types are also needed, find-implementations for interface member implementations. It also states the interface special case (derived interfaces plus implementing types) and the scope fallback, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, the description discloses enumeration rules (block-bodied methods, constructors, local functions, accessors), the scanning default, and truncation behavior for both groups and per-group occurrences. The instruction to check groups.hasMore and occurrences.hasMore independently is exactly the kind of operational detail annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five tight sentences, front-loaded with purpose before the exclusion note and the return/pagination contract. Dense but nearly every clause carries information; the one mild redundancy is restating the return payload shape (statementCount, symbol pointers, no excerpts) when an output schema already exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter, read-only analysis tool with a full output schema and annotations, everything an agent needs is present: what counts as a duplicate, what does not, default scope, default thresholds, and how to page through truncated results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds real meaning: minimumStatements counts top-level statements per block (default 3), and the two limit parameters are tied to independent hasMore flags. The scope parameter's fallback to the loaded solution is also clarified. It stops short of describing the scope kind enum values, but the schema handles those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource plus the exact matching rule: groups of whole executable blocks with identical statement text after whitespace normalisation. It immediately bounds the tool with 'this is not semantic clone detection', and 'identifiers and literal values remain significant' lets an agent distinguish it from any fuzzy similarity search among its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the purpose as locating duplication candidates for manual inspection, and enumerates what is out of scope (expression bodies, arbitrary statement subsequences). It also states the default scope (loaded solution when scope is omitted). No sibling tool is named as an alternative, keeping this short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so safety is covered. The description adds real value beyond that: the default cap of 100 results and the instruction to check implementations.hasMore before treating results as complete — a truncation trait not obvious from the schema. It stops short of describing ordering or whether partial results are stable across snapshots.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then routing, then scoping/pagination caveat. Every sentence carries information; the only mild redundancy is repeating the solution-scope default already stated in the schema for scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only query tool with a rich nested schema and an output schema, this covers everything an agent needs: what it returns (references), how to pick it over siblings, which projects get searched, and how to detect truncation. Return-value detail is correctly delegated to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents scope defaults, implementationsLimit default of 100, and zero-means-none behavior. The description restates the scope default and result cap, which reinforces but adds no syntax or constraint detail the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Finds implementations of a resolved interface or member') plus the return shape ('returns symbol references'). It explicitly contrasts itself with find-overrides and find-references, so an agent can distinguish it from the closest siblings without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States exactly when to use it ('to locate implementing types or members') and names the two alternatives with the conditions that select them ('overrides of a virtual or abstract member' vs 'source usages'). It also clarifies the scope default (loaded solution when scope is omitted). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them. It explains matching by name and method kind within the containing type, constructor behavior, possible inclusion of the selected callable, result ordering, the default limit, and hasMore truncation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, and the following sentences add only relevant constraints and behavioral details. Despite covering several nuances, it remains dense and free of filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and rich annotations, the description supplies the remaining behavioral context an agent needs: matching rules, exclusions, result ordering, truncation behavior, and the requirement to resolve a symbol first. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds some useful context around overloadsLimit and hasMore, but most parameter meaning is already carried by the schema, including workspace, symbol, and snapshot fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: it lists callable signatures for a resolved method or constructor. It clearly distinguishes the tool from symbol discovery by saying a callable symbol is required and pointing to search-symbols first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states the prerequisite (a callable symbol) and names search-symbols as the way to obtain one. It also gives exclusions: it does not resolve a call against arguments and does not collect inherited overloads, which helps select against related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already carry readOnlyHint/idempotentHint/destructiveHint=false, yet the description still adds real behavior: scope resolution rules ('a document scope searches its containing project', omitted searches the loaded solution), the 100-item default, the need to check overrides.hasMore, and that the member is not executed. It stops short of describing result ordering or performance characteristics, so a 4 rather than a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose first, then routing to alternatives, then scope semantics, then return/pagination note. Five tight sentences with no filler; every clause carries information an agent needs to call the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description needn't enumerate return fields, and it doesn't; it covers the pieces the schema can't — when to choose this vs. siblings, how scope defaults resolve, and the pagination caveat. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so scope, symbol, workspace, overridesLimit and expectedSnapshot are already documented in structured form. The description restates the scope-resolution and limit defaults but adds little that the schema doesn't already say (the zero-limit edge case is also in the schema), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource: 'Finds distinct overriding methods, properties or events for a resolved member.' It immediately disambiguates against the two nearby siblings (find-implementations, find-derived-types), so an agent can pick it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: 'Use this to follow virtual or abstract member overrides; use find-implementations for interface implementations or find-derived-types for type inheritance.' It names both alternatives and the condition selecting each, which is exactly what a sibling-rich tool listing needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, it discloses that declarations are included by default, that declarations and references share the 100-occurrence limit, and that results may be truncated — with an instruction to check references.hasMore. Some of this restates schema defaults (includeDefinitions, referencesLimit), but the truncation warning is genuine added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the purpose, then the alternative, then scope defaults, then the truncation caveat. Efficient overall, though the declaration/limit sentence partially duplicates schema-documented defaults.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be spelled out, and the description still flags the hasMore field that matters for completeness. For a nested 7-parameter tool with a required symbol identity, the guidance is sufficient, with only minor overlap against the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains scope, symbol, includeContext, referencesLimit, includeDefinitions, and expectedSnapshot. The description only echoes the scope default and the declaration/limit behavior, adding little syntax or semantics beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Finds source usages of a resolved symbol') plus what the results contain (locations, containing symbols, access classification). It explicitly distinguishes itself from the closest sibling, find-callers, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('locate usages or inspect writes') and names the alternative with its selecting condition ('use find-callers when you need incoming calls grouped by calling symbol'). It also states the default scope behavior when the scope argument is omitted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already say the tool is readOnly, idempotent, non-destructive, and closed-world. The description adds meaningful behavior beyond them: candidates are based only on three diagnostics, generated-looking documents are excluded by default, includeInternal widens the accessibility filter, scope defaults to the loaded solution, and the result is capped at 50 by default. The warning to check candidates.hasMore is a critical completeness caveat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core method and scope, then moves efficiently into usage warnings and parameter defaults. It is dense but not wasteful; every sentence carries operational value, though it could be split for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and annotations cover safety traits, the description supplies everything an agent needs for correct invocation: diagnostic basis, scope default, generated/internal filtering, result limit, and the hasMore caveat. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema itself handles the basics. The description still adds useful semantics that the schema does not state clearly: includeInternal widens the accessibility filter, generated documents are excluded by default, scope falls back to the loaded solution when omitted, and candidatesLimit defaults to 50 with a hasMore indicator. These are real clarifications beyond the schema's terse parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('identify candidate unused symbols') and grounds it in exact compiler diagnostics (CS0168, CS0169, CS0219). It clearly distinguishes itself from siblings by naming find-references and get-diagnostics as related but separate operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool ('review potentially removable locals and private members') and directs the agent to alternatives before acting: inspect find-references before removing code, or get-diagnostics for the underlying warnings. This is explicit when/when-not and alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: it discloses that work is staged rather than written ("does not write source files directly or create a Git commit"), which reconciles the destructiveHint=true / readOnlyHint=false profile with a agent's expectations. It also states the no-op case ("Already formatted text produces no change") and that a successful call returns mutation details plus a new snapshot.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, and every sentence carries information (scope, alternatives, preconditions, range semantics, return contract, workflow, negative scope). Slightly long, and the return-value sentence partly duplicates the output schema, which keeps it out of the top band.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, transaction-scoped, nested-object tool with an output schema, the description covers preconditions, idempotent no-op behavior, transactional lifecycle, and what it explicitly does not do. Nothing an agent needs in order to call it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3; the description adds real meaning by explaining that omitting range formats the entire document and that a supplied range is a zero-based start/length selecting the region passed to the formatter. It also names document and expectedSnapshot as required, though it does not add much on the snapshot echo semantics beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ("Stages Roslyn formatting for one document") plus the scoping constraint ("in the active transaction") and the option source (workspace formatting options). It explicitly separates itself from rename-symbol and code actions, so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use this tool ("Use this for formatting") and what to use instead for other needs ("rename-symbol or code actions for semantic transformations"). It also states the required preconditions (document, expectedSnapshot, active transaction) and the surrounding workflow: preview or review before commit, rollback discards.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly, idempotent and non-destructive, and the description goes further by disclosing the operating defaults: omitted scope means the loaded solution, Public minimum accessibility, obsolete symbols included, and a 100-symbol cap with a hasMore flag. It stops short of saying how the surface is shaped (flat list vs hierarchy by type/member) or whether inherited/private members are excluded, which matters for an inventory tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose then routing then defaults, with no filler. The final sentence is dense, stacking four separate defaults plus the hasMore caveat, which would read better split.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be restated, and the description still flags the one return property the agent must act on (symbols.hasMore). For a zero-required-parameter, read-only inventory tool with rich annotations, nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds genuine semantics beyond the schema: the meaning of an omitted scope ('searches the loaded solution'), the default accessibility threshold, and the fact that obsolete symbols are included by default (the schema gives includeObsolete no default). It does not explain scope.kind selection trade-offs beyond that, so not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists API declarations from source in the selected scope') and enumerates what each entry carries: symbol references, accessibility and obsolete status. It then explicitly differentiates itself from search-symbols (name lookup) and get-symbol-info (single-symbol inspection), so an agent can pick it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ('inventory accessible types and members') and names the two alternatives it is not, with the condition that selects each. The closing instruction ('Check symbols.hasMore before treating the inventory as complete') tells the agent how to use the result correctly, not just when to call it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower, yet the description adds real behavioral detail beyond them: counts follow the selected scope or the loaded solution, and source locations are truncated at 100 independently of counts. The instruction to check locations.hasMore before treating results as complete is exactly the kind of caveat an agent cannot get from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each earning its place: purpose, routing, scope fallback, truncation caveat. The opening sentence is a dense enumeration but the ordering is front-loaded and purposeful. Minor density cost in the first sentence keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return values, and it still covers scope fallback and truncation semantics that affect interpretation of the result. Annotations cover the safety profile, so nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description adds the semantic that counts and locations are governed independently and that omitting scope falls back to the loaded solution, which frames how the scope and locationsLimit parameters interact. Some of this overlaps the existing schema descriptions, so it is not fully additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb (summarises) and enumerates the exact resources returned: source references, callers, overrides, implementing types, and a public-surface indicator, all scoped to a resolved symbol. It is clearly distinguishable from the graph and dependents siblings by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use it ('static relationship evidence when planning a symbol change') and routes to two named alternatives, get-symbol-dependents and get-dependency-graph, with the condition that distinguishes each. No inference is left to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial operational detail beyond them. It explains the default 10-line window, 0-100 before/after line limits clipped at document boundaries, opt-in enclosing symbols and diagnostics, diagnostics scope limited to the selected span, per-collection limits with hasMore, and that source is not modified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and use guidance, then efficiently covers defaults, limits, opt-in behavior, and diagnostics scope. Every sentence adds operational value, and the slightly longer length is justified by the tool's nine parameters and many sibling alternatives.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, rich input schema, output schema, and annotations, the description is complete enough for an agent to invoke it correctly. It covers purpose, alternatives, key defaults, limits, scope boundaries, and read-only behavior without needing to repeat return-schema details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents parameters well; the description still adds meaningful semantics about clipping at document boundaries, opt-in defaults for includeEnclosingSymbols and includeDiagnostics, diagnostics covering only the selected span, and checking collection.hasMore. It does not add much about workspace, expectedSnapshot, or the location selector, but those are covered by the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it reads source around a location and returns resolved location, text, enclosingSymbols, and diagnostics. It also explicitly distinguishes itself from get-symbol-info and get-diagnostics, so an agent can tell which tool to select.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly when to use this tool: to inspect a search result or diagnostic in context. It also names alternatives and their purposes, get-symbol-info for symbol details and get-diagnostics for broader diagnostic analysis.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description goes beyond them by disclosing truncation behavior: independent defaults of 64 blocks, 32 regions, 32 operations per block, the hasMore flags to check, and the subtle caveat that successor ordinals may point at blocks omitted by the block limit. That caveat is genuinely non-obvious and prevents misreading results. It stops short of describing ordering or how the graph is rooted, so it is not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each doing distinct work: purpose, sibling routing, truncation semantics, input constraint. The core purpose and the alternative routing are front-loaded, and the caveats follow in the order an agent would need them.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with nested objects and an output schema, the description covers what the schema cannot: which sibling to prefer, how the three limits interact, and how to detect truncation. Return-value shape is delegated to the output schema, which is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the three limits are bounded independently, and the per-block operation cap interacts with the top-level block cap. The symbol-vs-location exclusivity is reinforced in prose. It does not explain what a symbol or location must resolve to (e.g. whether a non-executable symbol errors), so it is short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Builds a Roslyn control-flow graph') plus the exact input alternatives (a symbol, or the executable body enclosing a location) and the payload contents (basic blocks, reachability, successor ordinals, operations, flow regions). This is clearly distinguishable from analyze-control-flow and get-operation-tree, which are named separately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use ('inspect branching across an executable body') and routes the agent away with named alternatives and the conditions that select them: analyze-control-flow for reachability/exits of an exact statement region, get-operation-tree for nested semantic operations. The 'exactly one of symbol or location' constraint closes the remaining selection ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses defaults, pagination requirements, and a subtle truncation rule: omitted nodes also exclude their connected edges. That is exactly the kind of behavioral context an agent needs before calling the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well structured, with the core purpose and sibling routing front-loaded. The later sentences cover scope, defaults, and pagination without wasteful repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, the description supplies the crucial operational details an agent needs: default limits, how to detect truncation via nodes.hasMore and edges.hasMore, and the connected-edge exclusion behavior. Nothing important is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the schema carries most parameter documentation. The description still adds useful cross-parameter meaning: Project granularity uses selected projects, other granularities use selected source documents, omitted scope covers the loaded solution, and defaults are restated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it builds a dependency graph at Project, Namespace, Type, or Symbol granularity. It also specifies edge direction, which is meaningful domain detail, and explicitly distinguishes itself from get-symbol-dependencies, get-symbol-dependents, and get-change-impact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool: inspecting relationships across a scope. It also names the alternatives for single-symbol inspection and symbol-centred count summaries, and clarifies how scope granularity determines whether selected projects or source documents are used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: scope semantics (document scope keeps diagnostics whose primary source location belongs to that document; broader scopes can include findings without source locations), filter-before-limit ordering, the 200 default cap, and the hasMore truncation warning. That is above the annotation baseline but stops short of return-format or cost/latency detail, so a 3 is fair.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then alternatives, then scope semantics, then filtering/limit caveats. Every sentence carries information an agent would otherwise have to infer; nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be described, yet the description still flags the one thing that matters operationally: check diagnostics.hasMore before treating the report as complete. With five optional parameters, 100% schema coverage, and a matching safety annotation set, nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does add value beyond the schema by explaining that omitted scope means the loaded solution, how document scope narrows results, and that IDs/severities filter before the limit is applied — but it does not document the individual scope kinds or workspace selection beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns compiler diagnostics and diagnostics from analysers referenced by the selected projects') and explicitly contrasts itself with two sibling tools, analyze-async and get-document-options. An agent can distinguish this from the many other analysis tools in the list without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: general diagnostic inspection goes here, AsyncFixer's bundled rule set goes to analyze-async, document configuration goes to get-document-options. It also names the alternative and the condition that selects it, plus the default scope when the parameter is omitted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the read-only, idempotent, non-destructive profile, and the description adds meaningful behavior beyond them: source nullable directives can override the reported project-level context, and detailed parse/analyser data is omitted unless includeParseOptions or includeAnalyzerConfig is set. This tells the agent what the default view hides and why to request the optional enrichments.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, then alternatives, then behavioral caveats and optional flags. Every sentence carries useful routing or interpretation information, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema, output schema, and annotations, the description provides everything an agent needs: what is returned by default, what is omitted, how to request more detail, and which sibling tools cover related but distinct tasks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines the parameters, but the description adds real semantic value by explaining what includeParseOptions and includeAnalyzerConfig expose: documentation mode and preprocessor symbols, versus project configuration-file paths and syntax-tree analyser options. It also notes the nullable-directive override behavior, which helps interpret the returned configuration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource: it inspects configuration for a selected document and returns language version and project-level nullable context. It also distinguishes itself from adjacent tools by naming get-diagnostics and get-project-details as alternatives for different needs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing guidance: use this tool to understand the configuration behind diagnostic results, use get-diagnostics for findings, and use get-project-details for broader project configuration. The alternatives and selection conditions are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds non-obvious behavior beyond that: default node (200) and depth (16) caps, the truncated flag signaling omitted content, and root being null when syntax/semantic info is unavailable. It does not explain ordering or identity of nodes, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core statement, then alternatives, then defaults and edge cases; nearly every clause carries information. It is dense but not padded, though the final sentence stacks three separate facts that could be split more cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers the remaining unknowns for a read-only outline tool: defaults, truncation, and the null-root failure mode. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3. The description nonetheless adds meaning to nodesLimit and maxDepth by tying them to the truncation flag and framing them as defaults rather than fixed limits, which is context the schema's raw max/min does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns a semantic declaration tree for one document') plus the shape of the result (names, kinds, locations, nested children). It explicitly names the sibling tools it is not (search-symbols, get-symbol-info), so an agent can distinguish it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit selection rule: use this for navigating the structure of a known file, use search-symbols to discover declarations across documents, and get-symbol-info for detailed symbol metadata. Both alternatives and the condition that selects them are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new context: results are temporary, may contain paths and user-authored identifiers, and must not leave the machine. It stops short of saying how long 'temporary' lasts or what happens when a correlationId has expired.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with what is returned, followed by the sensitivity and restriction clauses. No filler and every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the description covers audience and data-sensitivity concerns. The remaining gap is edge behavior (unknown or expired correlationId) which an agent would want before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single correlationId parameter is fully documented in the schema as coming from the failed invocation. The description adds no syntax, format, or failure semantics beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (returns) and resource (temporary local diagnostic details) scoped to an unexpected tool or resource-read failure, which distinguishes it from general diagnostic tools like get-diagnostics. It does not name its closest siblings prepare-error-report and submit-error-report, so the reader must infer the split between fetching, preparing, and submitting an error report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear trigger (after an unexpected tool or resource-read failure) and a hard restriction (never submit externally, trusted local agent only), but it never explicitly points to prepare-error-report or submit-error-report as the follow-up path. Usage is implied rather than instructed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is real behavioral detail beyond that: fallback to the first immediate child when the selected node has no operation, default 200 nodes and maxDepth 8 with root at depth zero, truncation flags to check in the result, null-root behavior when nodesLimit is zero, and the requirement to echo the current expectedSnapshot. These are non-obvious edge cases an agent would otherwise get wrong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the capability statement, then alternatives, then edge-case behaviors, with no filler sentences. It is dense — five distinct behavioral claims packed into a short block — but nearly every clause carries actionable information, so it earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't explain return values and correctly does not. It instead covers what the schema cannot: node selection fallback, depth/limit counting conventions, truncation flags to check, and the snapshot-echo contract. For a nested 5-parameter tool with an output schema, this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description earns above baseline by interpreting parameters: it explains that maxDepth counts the root at depth zero, that defaults are 200 total nodes and maxDepth 8, and that nodesLimit of zero returns a null root — semantics not present in the schema's terse field descriptions. It does not add anything for the location/selection or workspace parameters, which the schema covers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Projects a semantic IOperation tree') and immediately enumerates what the projection contains (operation kinds, types, constant-value presence, source locations). This makes it clearly distinguishable from siblings like get-control-flow-graph, which are named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ('inspect the semantic structure at a source location') and then routes to alternatives by name and purpose: analyze-data-flow for variable flow sets, get-control-flow-graph for branches and successors. When-to-use and when-to-use-something-else are both stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context: partial definition and implementation parts are not combined automatically, metadata-only or implicitly declared symbols may return zero results, and results are capped with a hasMore flag the caller must check. These are exactly the non-obvious traits an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose first, then sibling routing, then edge cases, then pagination caveat — a clean front-loaded progression. Every sentence contributes a distinct fact; nothing restates the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only query with a rich input schema, an output schema, and full annotations, this description covers the remaining gaps: zero-result cases, why partial parts are not merged, and result truncation. An agent can invoke it correctly and interpret empty or truncated responses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries the parameter documentation burden and a baseline 3 applies. The description goes slightly beyond by tying the default 32-location cap to the hasMore field, telling the agent how to detect truncation, though it adds no detail on the symbol selector or expectedSnapshot parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Returns source declaration locations for a resolved symbol") plus the ordering guarantee (document path, source position). This is clearly distinguishable from siblings like get-symbol-info and find-references, which the description names explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the primary use case ("navigate split partial type declarations") and routes the agent to two named alternatives with their respective conditions (get-symbol-info for metadata, find-references for usages). No inference required to pick the right tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior those annotations cannot: documents are opt-in and exclude file contents, each collection is bounded independently, and callers must check hasMore per collection before treating results as complete. That truncation/pagination disclosure is exactly the non-obvious trait a consumer needs and is nowhere in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and routing guidance, then behavior, then the hasMore caveat — a sensible ordering with little waste. The sentence about collection bounds partially duplicates the per-parameter default values already in the schema, and 'bounded independently' is slightly opaque, keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only inspection tool with an output schema, everything an agent needs is present: how to locate the project, what comes back, that documents are opt-in without contents, and that per-collection hasMore must be checked. No expected-to-know detail is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description goes beyond it by explaining the semantic consequence of includeDocuments ('do not include file contents') rather than restating the schema's 'Whether documents should be included.' It still doesn't explain how project identity fields (projectId vs name vs path) are disambiguated or what happens on a limit of 0, so it stays below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Inspects one selected project') and immediately enumerates the returned facets: target frameworks, compilation/parse options, project and metadata references, analyzers. It explicitly names the sibling tools it is not (get-solution-structure, get-document-outline), so an agent can distinguish it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow: 'Use get-solution-structure to discover projects, then use this to inspect project configuration and dependencies.' It also names the alternative for document-level inspection ('use get-document-outline'), and states that document references are opt-in via includeDocuments — covering when-not to use the documents path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds real behavioral value: documents omitted by default, independent default caps, hasMore truncation flags per collection, and the ProjectStructureUnavailable failure mode. Slightly short of 5 only because it doesn't characterize cost/latency or ordering of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the primary mapping statement, then usage routing, then limits and return/error behavior. Dense but every sentence carries information; mild density cost from packing limits and truncation semantics into one paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, zero-required read tool with an output schema, the description covers purpose, alternatives, default-inclusion behavior, truncation signaling, and the named error case. Nothing an agent needs in order to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes beyond by restating the four independent default limits and flagging that documents are excluded unless includeDocuments=true. It does not explain the workspace parameter's identifier resolution or the guidance for choosing smaller limits, so it adds meaningful but not complete semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: maps the loaded solution into folders/projects with workspace-relative paths, target frameworks and direct project references. It explicitly differentiates itself from sibling tools (get-dependency-graph, get-code-context), so an agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit positioning ('Use this first to discover project and document selectors') and names two alternatives with their selecting conditions. Also states the includeDocuments prerequisite for returning documents, which is a concrete when/when-not rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: attributes are not instantiated and their constructors are not executed, results are bounded with attributes.hasMore signalling truncation, and interface declarations are never traversed. The Inherited/AllowMultiple handling is a subtle correctness detail an agent could not infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the sibling distinction are front-loaded, and the following sentences each carry distinct information (inheritance semantics, limit/truncation, no-instantiation guarantee). The result is dense but slightly overpacked, with several clauses chained into single sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needs no prose, yet the description still covers truncation signalling via attributes.hasMore and the inheritance edge cases. For a read-only, five-parameter, nested-schema tool, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's one-liner for includeInherited by defining its traversal rules (base types, overridden methods, properties and events; honours Inherited and AllowMultiple; excludes interfaces) and by restating the attributesLimit default of 50 with the hasMore truncation signal. The symbol selector, workspace and expectedSnapshot parameters get no added explanation, keeping this from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Inspects attributes attached to a resolved symbol') and enumerates what is returned (types, inherited flags, rendered constructor and named arguments). It explicitly separates itself from get-symbol-info, so an agent can distinguish the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the sibling alternative ('use get-symbol-info for general symbol details') and states the default scope ('Defaults to directly declared attributes'), which tells the agent what happens if it omits includeInherited. It stops short of stating prerequisites such as needing a resolved symbol from resolve-symbol first, which is implied but not spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered; the description adds real behavioral context beyond that: default page cap of 100, the 'check dependencies.hasMore before treating the inventory as complete' completeness caveat, and assemblies being included by default. It does not discuss cost, latency, or what happens for unresolved symbols, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the definition, then routing, then behavioral caveats — a sensible information order with no filler. It runs five sentences and mixes return-shape and caveat concerns; slightly tighter phrasing would read better, but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described; given that, the description covers what an agent still needs: scope (direct, outgoing), alternatives, metadata inclusion, assembly inclusion, and pagination completeness. Nothing required to invoke or interpret the call correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description still adds meaning the schema lacks, notably that includeAssemblies defaults to on and that results are capped at 100 unless a limit is set. It does not help with the heavier selector semantics (span vs selection, expectedSnapshot), but those are fully documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists distinct direct dependencies') and scopes it to a resolved symbol signature and supported executable operations. It names the exact siblings it must be distinguished from (get-symbol-dependents, get-dependency-graph) and clarifies that metadata symbols may appear, so an agent knows precisely what inventory it gets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this for outgoing relationships' and then routes the agent to the correct alternative for the reverse direction (get-symbol-dependents) and for cross-scope traversal (get-dependency-graph). Both the when and the when-not are present with the selecting condition stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description need not restate safety. It adds real operational context beyond them: a default cap of 100 dependents and the instruction to check dependents.hasMore before treating results as complete — a truncation behavior an agent would otherwise miss. It stops short of explaining what 'distinct enclosing symbol' collapses (e.g., multiple references in one method) or how snapshot staleness is surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each doing distinct work: definition, sibling routing, scope default, result-completeness warning. The most decision-relevant content (what it finds and which sibling to prefer) is front-loaded with zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be explained, and the description still flags the one output property that changes agent behavior (hasMore). For a read-only query with a nested but fully documented schema, nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so scope, symbol, workspace, dependentsLimit and expectedSnapshot are already documented in structured fields — and the description's scope and limit sentences largely restate those. The one added nuance is framing the limit as a completeness hazard via hasMore, but no new meaning is given for the symbol selector or expectedSnapshot beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Finds distinct enclosing symbols at source references to a resolved symbol' — which is precise enough to distinguish it from find-references (raw occurrences) and get-symbol-dependencies (outgoing edges). The name-plus-description pair leaves no ambiguity about what is returned: dependent symbols, not references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'use get-symbol-dependencies for outgoing dependencies, find-references for individual source occurrences, or get-change-impact for relationship counts.' That is a named alternative for each plausible confusion, plus a stated default-scope rule ('the loaded solution when scope is omitted').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint true and destructiveHint false, so the safety profile is covered by structured data. The description adds genuine behavioral context beyond that: XML docs are opt-in via includeDocumentation, results are bounded by independent declaration/parameter limits, truncation is signalled through declarations.hasMore and parameters.hasMore, and metadata-only symbols may return no source declarations. It does not address snapshot/expectedSnapshot concurrency semantics, but with annotations and an output schema present this is a solid contribution rather than an exceptional one.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then alternatives, then pagination and an edge case, so ordering is sensible and every sentence carries information. It is somewhat dense, packing limits, hasMore flags and the documentation flag into single clauses, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need no explanation, and annotations cover safety. The description still supplies the things structured fields cannot: upstream tool sequencing, sibling routing, independent bound defaults, truncation signals, and the metadata-only-symbol edge case. An agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema: it explains that includeDocumentation is an opt-in switch for XML docs, that declarations and parameters are bounded independently (32/64), and how hasMore flags signal truncation. It says nothing about the symbol selector, workspace, or expectedSnapshot parameters, which the schema already handles via its own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Inspects') plus a precisely scoped resource ('one resolved symbol'), followed by an enumeration of what is returned: accessibility, modifiers, associated type, declaration locations, parameters and return type. It also explicitly distinguishes itself from siblings by noting it operates on an already-resolved declaration, which the agent can tell apart from search-symbols or get-symbol-members without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the sequencing ('Use this after search-symbols or resolve-symbol') and names two alternatives with the conditions that select them ('use find-references for its usages or get-symbol-members to enumerate type members'). Both when-to-use and when-not-to-use are covered explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by specifying exactly what includeInherited pulls in and what it excludes (private, implicit, constructor/destructor members), what includeExplicitInterface widens to, that both default to false, and that the members collection is bounded with a hasMore truncation signal. The closing "reads the loaded workspace without modifying source" is mildly redundant with readOnlyHint, but the rest is substantive non-obvious behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then alternatives, then per-option semantics, then return/truncation behavior. Every sentence carries information an agent needs; there is no filler and no restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with nested selector objects and an output schema, the description covers the decision-relevant surface: scope defaults, flag semantics, bounded results and truncation handling. Return-shape detail is correctly deferred to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3, but the description supplies semantics the schema flags lack: the schema only says "Whether inherited members should be included," while the description spells out the inherited-member exclusions and the all-interfaces-vs-explicit-implementations distinction. It also states membersLimit defaults to 100 and points at members.hasMore for truncation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource pair ("Lists members of a resolved named type") and states the intent ("to inspect its declaration surface"), which is a distinct purpose from any sibling. An agent can differentiate it from get-api-surface, get-symbol-info, and find-implementations without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names two alternatives and the condition that selects each: get-api-surface for an accessibility-filtered API inventory, get-symbol-info for details about one member. It also establishes the default scope (explicitly declared members, including non-public), so the agent knows what it gets if it passes no flags.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only/idempotent/non-destructive, and the description goes well beyond: it discloses the heuristic's failure modes (may include tests using other members of the type, misses indirect helper-call dependencies), the exact candidate-selection rules (type name suffixes, GIVEN_ / _THEN_Should), that attributes alone don't select, scope defaulting, truncation signaling via tests.hasMore, and that tests are never executed. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded: purpose first, then caveats, then candidate rules, then parameter defaults and return behavior. Every sentence carries information, though the candidate-selection sentence is heavy and could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a heuristic analysis tool with a nested 6-parameter schema, an output schema, and rich annotations, this covers what an agent needs: what it returns, how truncation appears, and what it explicitly does not do. Only the workspace/expectedSnapshot concurrency parameters are left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters; the baseline would be 3. The description adds real value on top: testScope defaults to the loaded solution, testsLimit defaults to 100 with zero returning nothing, includeReasons defaults to false and doesn't change matching, and hasMore must be checked for truncation. Minor gaps remain (workspace and expectedSnapshot aren't explained).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opening clause states a specific verb and resource: 'Suggests tests to inspect after changing a resolved symbol, using static direct references.' This is clearly distinct from reference-lookup siblings like find-references. It doesn't explicitly name an alternative sibling such as get-change-impact, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly frames the use case (after changing a symbol, to pick tests to inspect) and gives strong exclusion guidance: 'not a coverage report or a guarantee of the tests affected' and 'Does not execute tests.' It stops short of naming which sibling to use for actual coverage or execution, so no explicit alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/destructive, and the description reinforces with 'no code is executed'. Beyond that it discloses scope behavior (search across the loaded solution), default inclusion of derived types, truncation via collection.hasMore, and that base/derived counts reflect only the requested depth — genuine context not in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling routing before diving into depth and limit semantics. Dense but organized; only the restated limit defaults are marginally redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, yet the description still flags the critical truncation signal (collection.hasMore) and the depth-scoped counting caveat. For an 8-parameter tool with nested symbol selectors, nothing essential is left ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description earns more by clarifying that maxDepth 'does not limit the transitive interface list' and that includeDerived defaults to inclusion, which is not obvious from the schema's untyped boolean. It also restates the 16/64/100 defaults already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Inspects the inheritance neighbourhood of a resolved named type') and enumerates exactly what is returned (type, baseTypes, interfaces, derivedTypes). It immediately distinguishes itself from find-derived-types, which appears in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use this for a combined hierarchy view; use find-derived-types when you need a scoped descendant search.' Both the affirmative case and the alternative with its selecting condition are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by disclosing non-obvious behavior: multiple source locations for partial declarations, and the fallback to a metadata definition record instead of decompiled source when no source exists. It also flags truncation via definitions.hasMore.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then alternatives, then return behavior, then limits — a sensible ordering with no wasted sentences. The closing 'Reads the workspace without modifying files' is largely redundant with readOnlyHint/destructiveHint annotations, the one minor inefficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter tool with nested symbol selectors and an output schema, the description supplies the selection guidance, the fallback semantics, and the truncation signal. Nothing an agent needs to call it correctly is missing, and return-value detail is properly delegated to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters including definitionsLimit's default and bounds. The description only restates the default of 32 and the hasMore check, adding little semantic value beyond what structured fields provide; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Locates declaration sites for a resolved symbol') plus the resolution policy ('preferring its source definition in the loaded solution'). It also explicitly names the sibling tools it is not, so an agent can distinguish it from find-references and find-implementations without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this to navigate to a declaration; use find-references for usages or find-implementations for concrete implementations' gives an explicit when-to-use with named alternatives. The qualifier 'resolved symbol' implicitly signals that resolve-symbol should run first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint and destructiveHint already declared, the description still adds substantial behavioral context: default limit of 50 action leaves, a hasMore flag, temporary process-local action IDs tied to the exact workspace snapshot, and the fact that listing stores references but does not stage changes or write files. This is exactly the kind of extra context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded: purpose first, then usage routing, then range semantics, then pagination and action-ID lifetime, then a clarifying non-mutation statement. Every sentence carries operational information, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex Roslyn discovery tool with nested snapshot, document, and workspace parameters, the description covers what an agent needs: how to select the target range, how to route the result to the next tool, how pagination works, and why IDs expire. An output schema exists, so it appropriately does not enumerate return fields, though it does mention actions.hasMore.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: an omitted range means the whole document, a zero-length range means a caret, and positions are zero-based UTF-16. It also reinforces the expectedSnapshot echo and the limit/hasMore interaction. It does not elaborate on kinds, diagnosticIds, includeProvenance, or workspace disambiguation, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Discovers applicable Roslyn Code Fixes and refactorings for a document, selection or caret.' It also distinguishes the tool from siblings by naming its downstream consumers, stage-code-action and prepare-fix-all, so an agent can identify its role in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it: to choose an actionId for stage-code-action in mutation-enabled modes, or a Code Fix with advertised fixAllScopes for prepare-fix-all. It also gives the precondition to echo expectedSnapshot and the invalidation rule to rediscover after changes or expiry. That is close to a complete when/when-not/alternative guide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds meaningful traits beyond the annotations: no network activity, that exception messages may contain Workspace data, and that users can strip exception messages during submission. These clarify side-effect and privacy behavior that readOnlyHint/openWorldHint alone do not convey. It does not explain the non-idempotent hint, leaving a small gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then adds the workflow in a second sentence. Efficient, though the second sentence is a run-on that packs three concepts together.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not strictly required, yet the description helpfully names the returned destination, payload string, and digest. Combined with the workflow and privacy notes, an agent has enough to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter (correlationId) is fully documented in the schema. The description adds no additional meaning to the parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (creates) and resource (the external payload) and clarifies scope with 'without network activity,' which implicitly distinguishes it from the sibling submit-error-report. The only weakness is that 'external payload' is slightly abstract rather than naming it as the error report payload.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow: present the returned destination/payload/digest to the user before calling submit-error-report when approval is required, and names the sibling alternative. It stops short of stating when this tool should be skipped entirely, so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnly/non-destructive, and the description adds substantial behavior beyond that: rejection above maxChanges (default 50), the separate 20-identity preview cap with hasMore/totalCount, the returned temporary actionId, and revalidation at staging. This is exactly the kind of operational context annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and the no-write guarantee, then layers constraints and the staging handoff. Dense and information-bearing throughout, though the single long paragraph could be split for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema and rich annotations, the description still covers the pieces an agent needs: lifecycle position (prepare → stage), rejection limits, preview truncation, and the ID handoff. Nothing essential to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents parameters; the description nevertheless adds meaning the schema does not — that actionId must be the originating reference, scope must be an 'advertised' value, and expectedSnapshot must match the state used to build the request. Slightly held back only because it does not detail the workspace parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Evaluates ... Fix All operation for a Code Fix from list-code-actions') and resource, and explicitly distinguishes itself from staging/writing ('without staging or writing source files'). An agent can immediately tell this apart from list-code-actions and the staging step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use inputs ('Supply the originating actionId, an advertised fixAllScopes value and the matching expectedSnapshot') and explicit exclusions ('refactorings and already-prepared Fix All references are not accepted'). It also routes to the downstream tool and warns which ID to use there, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: it explains that changes are merely staged, that source files are written only by transaction-commit, that this tool creates no Git commit, that an unchanged name produces no change, and that success returns mutation details plus a new snapshot. The 'staged, not applied' semantics are the single most important thing an agent needs here and they are stated plainly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the sibling distinction before prerequisites and behavior. It is dense — several clauses per sentence — but essentially every clause carries actionable information (defaults, workflow, no-commit guarantee). A minor trim would make it crisper.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent, nested-schema mutation with 8 parameters, the description covers purpose, prerequisites, safe workflow, flag defaults, return shape, and the blast-radius boundary. With an output schema present it correctly does not re-explain return values, only that a new snapshot is returned for subsequent requests.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real value the schema lacks: the default (false) for renameOverloads, renameInStrings, renameInComments and renameFile, and the specific behavior of renameFile as requesting Roslyn to rename the containing file for type symbols and staging the resulting path change. expectedSnapshot is also characterized as 'the current' snapshot.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Stages a Roslyn symbol rename and reference updates' — and immediately scopes it against 'code-action discovery for provider-specific transformations'. An agent can distinguish this from stage-code-action and resolve-symbol without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit about selection ('use this for a resolved symbol rename; use code-action discovery for provider-specific transformations') and about prerequisites ('Requires an active transaction, symbol, newName and the current expectedSnapshot'). It also states the mandatory follow-up workflow: inspect transaction-preview/transaction-review, then commit or roll back promptly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds real behavior: passing expectedSnapshot rejects stale locations, the default cap is 32 declarations with hasMore signaling, and metadata-only symbols may return no declarations. The only gap is that it doesn't mention workspace/snapshot prerequisites for obtaining the snapshot in the first place.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five tight sentences, front-loaded with purpose and immediately followed by disambiguation. The opening sentence is dense with parallel return artifacts but no sentence is padding; minor cost in readability only.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Annotations carry the safety profile and an output schema exists, so the description need not explain returns — yet it flags the pagination field and the metadata-only edge case an agent would otherwise miss. Nothing material for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still adds rationale the schema lacks, namely why expectedSnapshot matters (rejecting stale locations) and what declarationsLimit bounds (source declarations, default 32). It says nothing extra about location.span vs location.selection or workspace, which the schema already handles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (resolves) and resource (the symbol at a source location or selection) plus the three artifacts returned: symbol reference, reusable selector, bounded source declarations. It also names the sibling tools it is not (search-symbols, get-symbol-info), so an agent can distinguish it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use clause (turn a known location into a target for symbol inspection) and names two alternatives with the conditions that select them: search-symbols when only a name is known, get-symbol-info for detailed metadata. Routing is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: results are capped at 100 by default and the agent must check symbols.hasMore before treating results as complete, and it clarifies scope fallback. It stops short of describing result shape or ranking, keeping it at 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then usage/routing, then scope and result-cap behavior. Dense but every sentence carries routing or behavioral information; the closing 'Input: Provide query, metadataName, or both' is slightly redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering safety, an output schema covering return values, and a description covering routing, scope default, and pagination via hasMore, an agent has everything needed to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter, including the query/metadataName interplay. The description only restates the 'query, metadataName, or both' rule and that filters narrow candidates, adding little semantic depth beyond the structured fields. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Finds source type and member declarations') plus the matching mechanism (Roslyn name pattern) and semantic filters. It explicitly distinguishes itself from resolve-symbol and get-symbol-info, so an agent can separate it from the many sibling symbol tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('discover symbols by name') and names the alternatives with their conditions ('resolve-symbol for a known source location, then get-symbol-info to inspect a chosen symbol'). It also explains scope selection and its default (loaded solution when omitted).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the read-only/idempotent/non-destructive profile, yet the description still adds substantive behavior: that no workspace is loaded, no diagnostics are run, and recovery state is not repaired, plus that "Full" redacts to non-sensitive configuration. These are operational facts an agent cannot get from the annotation block alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Routing guidance is front-loaded and the detail-level breakdown follows logically. The closing "Result: ..." sentence largely restates the projection list already enumerated, costing some tightness in an otherwise dense paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values did not need explaining, yet the description still characterizes the projection per detail level and what the tool deliberately will not do. For a single-optional-parameter diagnostic read, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description goes further by spelling out what each enum value projects (Minimal = versions, MSBuild and Code Action component status, toolCount; Full = configuration, warnings, plugin status, recovery records) and notes Standard currently equals Minimal. That is meaning the one-line schema property description does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Reports Host health") and immediately adds a scope qualifier ("without requiring a loaded workspace") that separates it from workspace-bound tools. It then explicitly names the siblings it is not (workspace-status, get-diagnostics), so an agent can discriminate without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives positive routing guidance ("use this to diagnose startup, component availability, tool publication or effective operational policy") and pairs each sibling with the condition that would select it instead. It also states exclusions clearly ("does not load a workspace, run source diagnostics or repair recovery state").

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, the description discloses that staging does not write source files, successful staging consumes the action reference, and the returned snapshot must be used before selecting another action. It also states that prepared Fix All staging must match the exact prepared change set and document limit. It does not cover failure modes or authorization requirements, but the annotations already carry the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The action is front-loaded in the first sentence, followed by transactional sequencing and constraints. Despite covering a complex workflow, every sentence provides operational guidance and there is no obvious filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given annotations, a nested input schema, and an output schema, the description is complete enough for correct invocation. It explains the transaction lifecycle context, actionId sourcing, snapshot matching, and next-step alternatives without needing to restate return-value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the parameters are already well documented. The description adds useful meaning by explaining that actionId comes from list-code-actions or prepare-fix-all and that expectedSnapshot must match the state used to construct the request, including the prepared change set and document limit for Fix All.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: it revalidates and stages a selected Code Fix, refactoring, or prepared Fix All operation in the active transaction. It clearly distinguishes this staging step from discovery via list-code-actions, preparation via prepare-fix-all, and later transaction-preview/commit/rollback actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to start the transaction before discovery or preparation, where to get actionId, and how to use prepare-fix-all output with the matching expectedSnapshot. It also names the correct inspection and completion alternatives: transaction-preview or transaction-review, then transaction-commit or transaction-rollback.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: declining discards the handle, success means provider acceptance rather than remote delivery, there is no retraction, expired handles require a fresh prepared report, and reusing a retained successful handle returns the prior receipt without re-dispatching (which explains the idempotentHint). These are exactly the side-effect and irreversibility facts an agent needs given destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then prerequisites, consent semantics, failure modes, and result. Dense and largely waste-free, though the closing 'Result:' sentence partially restates what the output schema already returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers prerequisites, consent branching, no-op/decline outcomes, idempotent replay, expiry recovery, and what 'success' actually guarantees for each provider. Even though an output schema exists, the delivery-vs-acceptance caveat is behavioral, not structural, so it belongs here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is already documented as an opaque handle. The description still adds real meaning: the handle must be unexpired, must originate from prepare-error-report for the exact reviewed payload, and its reuse/expiry behavior changes the outcome.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (submits) and a specific resource (a reviewed unexpected-failure report via the configured provider). It also distinguishes itself from the two nearest siblings by naming prepare-error-report as the prerequisite and get-error-details as the local-investigation alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit call sequence (prepare first, review destination/payloadJson/payloadDigest, then pass the unexpired handle), an explicit exclusion (use get-error-details for local investigation), and an explicit decision rule for the consent modes: Prompt requests approval, Always skips it, Declined/unavailable sends nothing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it explains confirmation prompts in transactional vs autonomous-trusted mode, that a completed write ends the transaction, and that an empty revision yields NoChange while leaving the transaction active.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then alternatives, parameters, approval model, completion semantics, and a concurrency caveat. Every sentence carries distinct operational information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent, client-confirmation-gated mutation, this covers approval flow, failure modes, state transitions, and concurrency hazards. An output schema exists, so the description rightly only points to the fields worth checking rather than enumerating return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents expectedSnapshot's echoed-snapshot semantics, so the baseline is 3. The description adds value by tying the snapshot to call outcomes — the expected snapshot must be current, and a stale or empty revision produces NoChange.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Writes the active transaction changes to source files.' It also disambiguates from a similarly named concept with 'This does not create a Git commit,' so an agent will not confuse it with version-control operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to siblings: inspect transaction-preview first, use transaction-rollback to discard. It also states the preconditions for a successful call (supply current expectedSnapshot, avoid concurrent edits on commit-owned paths) and the mode-dependent confirmation behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and idempotentHint=false, but the description adds materially: mutations are in-memory and do not write source files, snapshot chaining semantics (use the returned snapshot for subsequent mutations), canUndo/canRedo reporting, and rejection beyond history. This goes well beyond the structured safety flags.