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

Discloses traits well beyond the annotations: in-memory session lifetime (90 minutes, 8 sessions), MSBuild side effects writing under obj/, uncommitted edits are read, long runtimes with progress token, and that cancellation still completes so a retry is cheap. It correctly frames itself as not modifying source while readOnlyHint=false is explained by the obj/ generated-file caveat, so no contradiction. Minor gap: it does not say what happens when the 8-session cap is exceeded (eviction policy beyond the number).

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 purpose then the optionality rule, and the return-field list and incompleteRun caveat are genuinely load-bearing given there is no output schema. It is long, though, and the parameter paragraph re-explains precedence that the schema already carries, which is the main place words could be cut.

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 no output schema, the description enumerates the returned fields including conditional ones (incompleteRun, configInit, agentWiring) and points to solution_config_status and get_diagnostics for follow-up. It also warns that absence of incompleteRun is not an all-clear, which prevents a realistic misread of the result.

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 descriptions already spell out the config precedence chain in detail, so the description largely restates it. It does add one useful operational rule not in the schema — "normally pass only solutionPath" and that layerProfile overrides only the layer axis — but the dbPath/layerProfile precedence material is redundant with the schema, so this sits at the baseline-plus level rather than clearly above it.

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 and technology (analyze a .sln/.slnx/.slnf with Roslyn) and states its role as the entry point that produces the session_id other tools consume. Siblings like refresh_session and get_diagnostics are explicitly positioned against it.

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-not-to-use guidance ("Calling it is optional... do not call it just to run a query"), the concrete reasons to call it anyway (read the answer first, pass layerProfile/dbPath), and the correct alternative after editing .cs files (refresh_session). This is about as routing-explicit as it gets.

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?

Far exceeds the annotations: it discloses dual persistence (config/master DB plus the git-tracked <SolutionName>.aicb.json sidecar), names the returned sidecarPath and advises committing it, explains merge semantics for unnamed axes, and specifies refusal-before-write behavior for unreadable/locked sidecars plus the warning path when the file becomes unreadable mid-write. Validation rules (invalid matchType rejected not defaulted, non-boolean keep rejected, misplaced keep rules relocated to keepNamespaces) are also spelled out.

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 lead sentence is well front-loaded and every topic is relevant, but almost all of it is delivered as one enormous run-on sentence stringing together JSON examples, keep-rule semantics, DB/sidecar duality and failure modes. Splitting into bullets or short sentences would make the same content far easier to scan; some dbPath default detail also duplicates 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?

For a destructive, non-idempotent, 9-parameter write with no output schema, the description covers write targets, merge behavior, validation failures, partial-failure warnings and the returned sidecarPath. The main residual gap is that the return payload beyond sidecarPath (e.g. created profile IDs) is never characterized, and there is no guidance on re-running against an already-initialized slot.

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% (baseline 3), but the description still adds meaning the schema does not carry: full literal JSON shapes for proposalJson and testProposalJson, the matchType enumerated values and that they are validated, the "keep":true keep-rule semantics and the keepNamespaces sidecar key, and the clarification that testProjectRules match PROJECT names. This is substantive semantics, not restatement.

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 ("Apply") and a precisely enumerated resource (Layer Profile + Exclude-Namespaces + Test Profile for a solution), then states what it materializes (custom layer profile / exclusion list / test profile) and that they are activated and marked initialized. An agent can tell this apart from check_solution_config_drift, solution_config_status and init_solution_config 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 concrete selection rules: at least one axis must be non-empty, empty arrays/slots are skipped, testPreset is mutually exclusive with testProposalJson, and "Omit for a test-only apply" is implicit from the schema text. It never names a sibling tool as an alternative (e.g. check_solution_config_drift for verification or init_solution_config for first-time setup), so routing against alternatives 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 only establish readOnly/idempotent/non-destructive; the description adds substantial behavior the agent could not otherwise know: the leading <TRUNCATION> block semantics and its per-section '+N more' counterpart, the 80-entry section cap, the 2500-type layer-map ceiling, multi-TFM dedup keeping the newest TFM, and degraded output on recalled sessions (hotspot line counts unavailable). None of this contradicts the 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?

The lead sentence is well front-loaded, but the body is a ~320-word wall of ALL-CAPS emphasis, dashes and parentheticals, and roughly a third of it re-explains parameters already fully documented in the schema. The truncation-block paragraph is placed ahead of the more decision-relevant capability summary, so an agent must read deeply before learning what the tool actually 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?

With no output schema, the description carries the burden of explaining the return value and does so thoroughly: the section inventory, truncation signalling, size bounds at scale, test exclusion, and session-type behavior. It also flags the fallback path when output would exceed the token cap, leaving no material gap 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 description coverage is 100% and each of the four parameters already carries a detailed default-plus-rationale entry, so the schema does the heavy lifting. The prose largely restates those entries (the includeTests and summaryOnly rationales are near-duplicates of the schema text) rather than adding new syntax, interaction, or edge-case 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 ('Orient on a whole solution', renders a structural macro/architecture overview) and enumerates exactly which sections are produced (layer map, dependency graphs, role graph, entry points, hotspots) and which are excluded (no per-type/per-file source blocks). It explicitly distinguishes itself from export_markdown ('27-29 MB firehose'), call_graph, explain_symbol and find_symbol, 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 an explicit ordering rule ('Use this FIRST ... then get_context / explain_symbol to drill into a symbol') plus named alternatives with the conditions that select them: export_markdown for the full set, find_symbol/call_graph/get_context to drill in, includeTests=true for test projects, summaryOnly for 200+ project monoliths. When-not guidance is present too (method-level call graphs deliberately omitted; tests excluded by default).

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 behavioral context beyond them: conservatism in both directions, that refutation requires a STRONG covering test per find_tests_for tiers, that name-only matches yield indeterminate with the tier split, and that typo'd/invented axes return indeterminate rather than a false confirm.

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 return values, and most sentences carry distinct information. It is dense with parenthetical qualifications that border on overload, but almost none 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?

No output schema exists, yet the description spells out return values (confirmed/refuted/indeterminate with evidence) and the edge-case returns (unresolved names, unrecorded axes). With 2 fully-covered params and annotations supplying safety, 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%, but the description adds real meaning beyond it: it decodes each claim token ('absent' means developer-declared none, NOT unknown; 'unknown' means no provenance entry), explains the Symbol vocabulary shared with find_usages/find_tests_for/impact_of_change, and defines what an axis is with examples (role/layer/domain/context/responsibility).

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 (check/assert) and a specific resource (a NEGATIVE claim against the analyzed model), and enumerates the three supported claim tokens with their precise meanings. It is clearly distinguishable from the positive-verification sibling verify_claim.

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 ('validate this service is untested or role is explicitly unset before relying on it') and defines which claim shapes are in scope. It does not, however, name verify_claim as the positive-claim alternative, so the sibling routing is implied rather than 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 declare readOnly/idempotent/non-destructive, but the description adds constraints they cannot convey: max 16 sub-queries (over-limit fails the whole call), an unresolved sessionId failing the whole call, per-item refusal semantics, partial success (ok:false + error while the rest still return), a ~9000-token shared response budget with omission behavior pointing to direct invocation, and the 'note' field for unrecognized args being ignored not rejected. This is rich behavioral disclosure well beyond the annotation set.

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 usage then return shape then failure modes then the dispatchable/refused registry. Dense and mostly waste-free for the surface area covered, though the sessionId-omission point is stated twice and the refused-tool list is long.

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?

No output schema exists, yet the description supplies the return shape ({results:[{tool,ok,result|error}], count, okCount} in query order), per-item vs whole-call failure behavior, and budget-driven omission semantics. For a dispatcher with a nested query registry, this is complete enough to invoke 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 baseline is 3, but the description adds real meaning: the required {tool, args} shape, that args must omit sessionId, a concrete worked example, the max-16 bound, and that sessionId accepts an absolute .sln/.slnx/.slnf path analyzed on first use. It goes well 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?

States a specific verb+resource: 'Run several read-only query tools in ONE round-trip against one shared session.' It also explicitly distinguishes itself from its sibling measure, which 'reports what each answer would cost instead of returning it.' An agent can tell what this does and what it is not 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?

Explicit trigger: 'Use it whenever two or more questions do not depend on each other's answers.' It also enumerates what must NOT be batched — mutating tools, poor batch members (evaluate_change_set, init_solution_config, prepare_task, review_context), tools needing a second session/snapshot, and session/config/server tools — with the registry's names. When/when-not coverage is unusually complete.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description still adds substantial undisclosed behavior: a 500-edge cap with a truncation flag, cycle-safety, constructor-edge keying as 'Ns.X.X(params)', contract/abstract-member expansion at every hop, and the viaContract/creditedBy/rootedAt result fields. That 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?

Purpose and direction semantics are front-loaded, and every sentence carries non-redundant information. It is a single dense block of prose with no structural breaks, which makes the later rootedAt/viaContract guidance harder to scan than it needs to be.

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?

There is no output schema, so the description must explain returns, and it does: (caller, callee) edges with lookup keys, truncation flag, viaContract with implementation counts, creditedBy, and rootedAt. For a tool whose main failure mode is an unexpectedly huge or empty graph, the diagnostic guidance is present.

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 genuinely adds semantics the schema does not: the bare-vs-'Type.Method' rooting distinction (union of all same-named declarations vs overloads of one type), and the consequence of 'callers' direction on node expansion. Depth is only echoed as 'depth-limited' without discussing bounds, so it stops 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?

Opens with a specific verb+resource+scope: 'Build a depth-limited call graph rooted at a method NAME'. Immediately enumerates the two directions with their meanings, so an agent can distinguish this from impact_of_change or find_usages 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 concrete conditional guidance: bare name is a union of every same-named declaration and can inflate payload, so 're-query a rarer or qualified name' when rootedAt is too big, and check rootedAt when the edge list is empty. What's missing is explicit routing (e.g., 'use impact_of_change instead when you need cross-contract impact') – impact_of_change is only referenced descriptively.

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 annotations already declaring read-only, idempotent, non-destructive behavior, the description adds substantial operational context: capped results at 200, sorting rather than ranking, what each hit contains, which units are scanned, and what kinds of external references are not recorded. It also explains empty-result notes and test-filter behavior, giving the agent a realistic model of the tool's limitations.

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 and lengthy, but it is front-loaded with purpose and usage, and most sentences add concrete caveats an agent would otherwise miss. A few details repeat schema descriptions, and the density makes it harder to scan, keeping it just below the top score.

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?

The tool has no output schema, but the description explains the return envelope, hit fields, ordering, cap, and omitted fields. It also covers important edge cases such as note messages, unresolved references, top-level statements, and test filtering, making the definition complete 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?

Although schema coverage is 100%, the description adds real meaning beyond the schema: pattern is a case-insensitive substring of the whole call key including parameter lists, it is an open vocabulary with no did-you-mean, empty results are strong but not absolute, and broad patterns truncate at 200. It also clarifies scope matching on namespace segment boundaries and the test-inclusion default.

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 states a specific verb and resource ('find the code that calls an EXTERNAL member') and immediately distinguishes it from find_usages and find_by_side_effects. An agent can tell exactly what this tool searches and what it does not.

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 names use cases (AOT/trimming readiness, security surface, dependency footprint) and gives concrete example patterns such as 'Process.Start'. It also clarifies that 'pattern' is the only search argument and there is no 'symbol', which prevents misuse.

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/non-destructive/idempotent, but the description adds real context: it changes no configuration and creates no solution row, a missing dbPath is refused, an empty one is not opened, an older one is upgraded on open, and it needs a live session rather than a recalled one. It also explains which statuses mean 'not judged' (built-in-preset, not-configured) and what sidecarProblem means. The gap: the 'upgraded on open (schema, built-in rows)' detail is a write side effect that sits awkwardly next to a pure read-only framing, and the description never reconciles that tension.

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 verdict question before any of the return-shape detail, and the positioning against solution_config_status comes early where it matters. It is dense and long, with several back-to-back clauses (status thresholds, sample caps, sidecarProblem, dbPath caveats) that could be split for scanability, but almost every sentence carries operational content.

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?

There is no output schema, and the description compensates thoroughly: it enumerates the returned keys (layer, exclusion, test, source, name, status, stale, considered, sample, reason, sidecarProblem), defines the staleness thresholds, and explains that an 'ok' with a sample is still worth reading. For a multi-axis diagnostic tool this is complete enough to call and interpret 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, but the description adds genuine selection guidance: normally pass only sessionId, an absolute .sln/.slnx/.slnf path also works, and dbPath only if the session was analyzed with it — otherwise the result judges a configuration the analysis did not use. That conditional is not in the schema and prevents a real misuse.

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 object: check whether a solution's active Layer Profile, Exclude-Namespaces and Test Profile still fit the code. It also explicitly distinguishes itself from the nearest sibling, solution_config_status, which reports WHICH configuration is active rather than whether it still fits.

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 concrete trigger conditions ("on a solution configured a while ago, or when layer or exclusion results look off") and names the relevant alternatives and remedies: init_solution_config and apply_solution_config for a stale axis, solution_config_status for the 'which/where-from' question. It also states a scoping exclusion: on a never-configured solution only exclusion.excludedApiAreas is evaluated.

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 still adds substantive behavior: syntactic name-based comparison with no method-body diff, the exact structure of returned added/removed types and signature changes, and the conditional 'note' emitted when the baseline hash matches and the diff is empty (including the cross-analyzer-build caveat). That is real context an agent could not get from the 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?

Core operation is front-loaded in the first clause, and each sentence maps to a distinct concern (baseline selection, filtering, return shape, prerequisites, semantics, note behavior). It runs long and the 'note' discussion is dense with parentheticals, but no sentence is pure 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 no output schema, the description carries the return-shape burden and does so ('added/removed types plus, per changed type, added/removed methods and signature changes'), plus the self-comparison caveat an agent needs to interpret an empty result. Nothing required for a correct call 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 still earns credit by explaining the snapshotsBack indexing as a history walk ('0=newest saved, 1=the one before'), the dbPath default, and the two narrowing axes together with the consequence of a filter that empties a non-empty diff. Most of this value is already duplicated in the schema property descriptions, which keeps it at 4 rather than 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?

Specific verb and resource: 'Diff the current session against a previously saved snapshot of the SAME solution', with the baseline selected by snapshotsBack. It also states the diff's granularity (name-based, syntactic, no method bodies) and return shape, which clearly separates it from save_session and from change-oriented siblings like impact_of_change or evaluate_change_set.

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 a hard prerequisite ('Requires a sessionId and at least one earlier save_session') and routes one edge case to an alternative tool ('check the spelling with find_symbol'). It never states when to prefer impact_of_change or evaluate_change_set over this diff, so it stops short of full 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: the one-hop limitation, testReachDepth/viaDispatch semantics, the alphabetical 200-item cap, the definition of test code, constructor-as-hop behavior, accessor calls not read, and the judgedUnits denominator. This is exactly the behavioral disclosure an agent needs to interpret results correctly.

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 critical one-hop caveat are front-loaded, and the sections (returns, what counts, population) are logically ordered. It is long and carries some rhetorical filler ('A gap count without its denominator is meaningless', 'THE LIST IS ONE HOP'), but the density is largely justified by the absent output 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 no output schema, the description carries the return-value burden and does so thoroughly, naming every field (scope, note, symbolsScanned, uncovered, verifiedAbsent, transitivelyReached, judgedUnits, testProjectsExcluded, testFixtureTypesExcluded, reachedOnlyThroughDispatch) plus the edge cases for symbolsScanned 0 and the note field.

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: scope is case-insensitive and matched on segment boundaries, 'solution' is the default, and there is no test toggle. It also notes sessionId accepts an absolute .sln/.slnx/.slnf path analyzed on first use.

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 ('List what is NOT covered in a scope') and enumerates the two result categories, uncovered and verifiedAbsent. It also explicitly distinguishes itself from find_tests_for ('asks the opposite question for one symbol'), so an agent can route between the two 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 when-to-use ('find untested code before claiming coverage') and names the alternative sibling with the condition that selects it. It also warns about the primary misuse case (treating the one-hop list as a coverage measurement) and tells the agent to narrow scope when the 200-item cap bites.

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 safety profile is covered; the description adds substantial beyond-schema behavior: how property accessors, consts, and enums render, that the type list is capped with the true total in the envelope, that it works on live AND recalled sessions, and honest "Known v1 simplifications" about accessibility computation and modifier-omitted types.

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 most sentences carry load-bearing detail. However, the volume is high for a 4-param read-only tool, with heavy ALL-CAPS emphasis and stacked parentheticals that reduce scannability and add redundancy (accessibility/rendering rules are stated twice).

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 no output schema, the description carries the return-shape burden and does so well: it explains declarations are compact signatures, that member lists are whole while types are capped, and that the envelope carries the true total. Combined with the simplification caveats, an agent has everything needed to call and interpret 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, but the description adds real semantics the schema lacks: includeInternal surfaces the internal/private-protected family, and a namespace prefix matching no namespace yields a 'note' ahead of typesScanned 0. It reinforces the defaults for scope and includeTests rather than merely restating them.

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 ("List") and resource ("PUBLIC API SURFACE of a solution or namespace") and immediately clarifies scope (externally-visible types with their members). It differentiates itself from siblings by naming compare_with_previous and diff_public_contract, plus the "public-API digest, not a firehose" framing that separates it from a full-documentation tool.

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 use cases ("review a public contract before changing it, or as the baseline for a contract comparison") and names the chaining alternatives (save_session then compare_with_previous, or diff_public_contract, noting the latter is outside the default profile). It does not state an explicit when-not condition beyond the firehose contrast, so it falls just 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 establish read-only/idempotent, but the description goes well beyond them: it discloses the 100-cycle cap, ordering (solution-spanning first, then largest), witness edges being EXAMPLES not a work list, edgeCount/typeEdgeCount semantics, edgesTruncated capping (with the namespace list still complete), and how edges are derived from recorded type facts. This is exactly the extra behavioural context a caller 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?

Front-loaded with purpose in the first clause, then alternatives, then return semantics. It is long, and the witness-edge paragraph is dense, but with no output schema every sentence is doing load-bearing work; only minor tightening is possible.

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?

No output schema exists, so the description must carry return semantics and it does: field list, caps, ordering, truncation flag, and the interpretation rule for a zero count under each scope. Combined with annotations covering safety, an agent has everything needed to call and read 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, but the description genuinely adds meaning: scope 'narrows the report, not the graph' and returns a whole cycle when any member matches the prefix; includeTests is justified (test->production is one-way, not an architecture cycle); sessionId accepts a .sln/.slnx/.slnf path analyzed on first use. This exceeds what the schema alone conveys.

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 ('Detect circular NAMESPACE dependencies') and immediately scopes it as cycles among groups of namespaces, explicitly contrasting with the 'layer-violation insight in list_insights'. An agent can distinguish it from that sibling and from other architecture tools 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 an explicit trigger ('Use it before splitting an assembly or moving types between namespaces') and a precise division of labour with list_insights (direction rule vs mutual entanglement). It also explains the interpretation of results under each scope value, including that an unknown prefix likewise answers zero, which is real guidance, not just context.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond them: token estimates per page for budgeting, route expansion into reading order, deduplication of repeats, and unknown ids being named back rather than dropped.

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 what it is, then how to call it, then the page catalog. The page enumeration is long but each entry earns its place as a routing aid; only minor tightening is possible.

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 single optional-array parameter tool with rich annotations and no output schema, the description covers invocation modes, valid values, edge behavior, and prerequisites. 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 baseline is 3, but the description goes further by enumerating every valid page id with its content summary ('overview', 'install', 'first-context', 'navigation', 'solution-config', 'glossary') plus the 'init' route — effectively documenting the valid value domain 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?

The first sentence names the specific resource (the aicb operating manual) and explicitly demarcates its scope: 'how to USE this server, as opposed to what it can tell you about your code.' That contrast cleanly separates it from the ~50 sibling code-analysis tools.

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 explicit routing conditions: 'Start here if you have not used aicb before', explains that a bare call returns the directory, and gives per-page when-to-use cues (e.g. 'for setting aicb up somewhere else, or finishing a half-done setup'). It also notes 'No session and no solution needed', removing a common prerequisite question.

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?

Far exceeds the annotations: states the changeset is applied as an in-memory Roslyn overlay with NO disk write and the session untouched, that the gate is advisory only because an MCP tool cannot block (real gate is CLI --fail-on), that oldText must occur exactly once or it is an error, and how layer/quality profiles are resolved on both delta sides.

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 and most sentences carry non-redundant behavioral detail, but the prose is extremely dense and long for a four-parameter tool, packing profile-resolution and precedence caveats into a single flowing paragraph that is hard to scan.

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?

There is no output schema, yet the description covers the verdict shape (pass/warn/block), the delta-vs-session finding semantics, the available policy values, and the advisory-only caveat, so an agent has everything needed to call and interpret it.

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: the oldText/newText anchor-patch shape, operation defaulting to 'modify', empty newText deleting, and precisely what dbPath changes (QualityProfile thresholds + default layer profile with precedence rules).

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 ('which findings would this edit INTRODUCE') with a clear noun: an advisory policy gate over a proposed change set. It also proactively rules out the confusingly-named sibling by declaring 'apply_change_set is out of scope', so an agent can separate the preview from the write.

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 to ask BEFORE writing, names the cheapest form (anchor patch) versus the full-text form required for add/delete, and rules out apply_change_set. It stops short of naming which sibling to use instead for the adjacent 'what will my change impact' question, so selection against impact_of_change/review_context is left implicit.

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 substantially beyond them: manifest comments distinguishing '(none)' honest negatives from 'not asked', a 'run:' segment flagging incomplete analysis, dropped unknown include tokens being reported, per-project block folding and multi-TFM dedup. It also discloses budget-driven dropping and that the center symbol degrades to STRUCTURE rather than vanishing — exactly the behavior an agent needs to interpret output.

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 contract, and nearly every sentence carries new information (axis semantics, manifest honesty, dedup rules). It is nonetheless a single very long paragraph with no structural breaks, and the trailing multi-TFM dedup sentence is the weakest-value item given find_symbol parity.

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 no output schema, the description carries the full burden and does so: it describes the return artifact, the manifest preamble, the lean-vs-full document difference, and how truncation appears in the output. Nothing an agent needs to call it correctly or interpret the result 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 earns above that by explaining cross-parameter behavior the schema does not — that an empty include returns source only and the manifest names the available axes, that invalid include tokens are reported as dropped, and that a bare symbol name seeds all matching declarations and can be budget-capped. It largely restates the budget and lean semantics already fully documented in the schema, 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?

Opens with a specific verb+resource ('Explain a symbol: its source PLUS a chosen environment') and immediately defines the output artifact (one dense AI-Builder-Markdown slice). It explicitly distinguishes itself from the composite alternative ('instead of 4-6: get_context + find_usages + find_implementations + find_tests_for') and from export_markdown/find_symbol, so an agent can place it among siblings 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?

States when to use it (the cold-read in a single call, one symbol's world), when to use something else ('use find_symbol to disambiguate', 'prefer it over export_markdown for one symbol's world'), and what an empty 'include' means. The 'prefer it over' clause plus the named alternatives covers both directions of 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 declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the write profile is already partly known; the description still adds real value by disclosing the 16,000,000-byte response ceiling, the refusal-with-size behavior, the profile-driven rendering path, and the file-vs-inline return difference. The main gap is that it never warns that writing outputPath overwrites an existing file, which is exactly the behavior destructiveHint=true implies.

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?

It is front-loaded with purpose before constraints, and the long size-ceiling and profile-fallback sentences each carry operational information. It is on the verbose side and could be tightened, but nothing is pure 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 no output schema, the description correctly explains return values (Markdown content vs a short confirmation when outputPath is set) and covers defaults, fallbacks, size limits, and alternatives. Only the overwrite/destructive side of writing outputPath is left implicit, which matters given destructiveHint=true.

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 facet, format, sessionId, and outputPath in detail (including fallbacks and accepted path forms). The description mostly restates those semantics ('the chosen facet's template ... is used'), adding only the practical hint to use outputPath for anything but a small solution, so baseline 3 is appropriate.

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 ('Render the cached analysis of a session as AI-Builder Markdown') and immediately adds the distinguishing trait 'No re-analysis - instant.' It also names the sibling tools that serve adjacent needs (architecture_overview, get_context, explain_symbol), so an agent can separate this from other export/overview 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?

It states explicit routing conditions: 'Pass outputPath for anything but a small solution', and 'For a bounded view prefer architecture_overview ... or get_context / explain_symbol'. When-not conditions are also covered via the size-ceiling refusal for whole-solution renders.

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 adds substantial context beyond them: markup is re-read from disk each call so no refresh_session is needed, only the {Binding} markup extension (plus {CompiledBinding} in .axaml) is visible and code-behind/element-syntax/{x:Bind} bindings are invisible, lists are capped at 200 while counts are true totals, and test projects are scanned. This is rich disclosure well beyond the annotation set.

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?

It is long, but front-loaded with purpose and routing first, then output shape with/without path, then caveats, then param notes – each block carries distinct information. The final paragraph mildly restates schema content (case-sensitivity, scope values), which costs a point but does not obscure the structure.

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?

There is no output schema, so the description must carry the return contract, and it does: it enumerates sites/siteCount/byForm/deeperSegmentSites/pathlessBindingCount/scannedFileCount/sitesTruncated for the path view and members/distinctMemberCount/totalSiteCount for the inventory view, plus the truncation caveat. Nothing needed to invoke or interpret the tool 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 adds real meaning the schema lacks: path matches the whole path or its ROOT segment ('Foo' finds {Binding Foo} and {Binding Foo.Bar}), the 'Bar' of Foo.Bar is reported separately in deeperSegmentSites, a leading 'DataContext.' on elementName/relativeSource is a hop, path is not resolved as a symbol, and an unknown form matches nothing. Some overlap with the schema's own field descriptions 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?

The description states a specific verb and resource – listing {Binding ...} sites in the solution's .xaml/.axaml markup that name a member path. It immediately distinguishes itself from find_usages ('carries a markup edge for a root member bound against the DataContext; this tool lists every site, redirected bindings included') and find_unresolved_bindings, so an agent can select 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?

It provides explicit routing rules against two named siblings and a concrete trigger: 'Use it before renaming or deleting a view-model member.' It also states when zero results are meaningful ('zero sites means verify before renaming or deleting, not proof'), which is exactly the exclusion guidance an agent 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?

Annotations already declare readOnlyHint/true, idempotentHint/true and destructiveHint/false, so the safety profile is covered by structured data. The description still adds real context the annotations cannot: deterministic Roslyn resolution, works on recalled sessions, and a hard cap of 200 results. Baseline 3 is appropriate since the added value is moderate rather than deep.

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 scoping constraint are front-loaded, but the middle is dense and repetitive: the kinds values are re-listed even though the schema enumerates them, and attribute examples appear twice ('[Obsolete]', '[ApiController]'). Several clauses about partial types and linked-file twins feel like output detail packed into a sentence that reads as run-on.

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?

No output schema exists, yet the description explains what comes back: the raw stored attribute list travels with each hit, 'fullName' marks namesake type rows and 'project' the twin rows of a linked file, plus the 200-item cap. An agent has enough to call it and interpret the response without guessing.

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 would be 3, but the description goes further by spelling out the attribute-name normalization ('Obsolete', 'ObsoleteAttribute', 'System.ObsoleteAttribute' all match) and clarifying that the 'method' axis includes constructors and accessors named .ctor/get_X/set_X. Those semantics are not derivable from the schema alone. The kinds enumeration is largely duplicated from the schema, 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?

A specific verb plus resource ('Find symbols ... that carry a given ATTRIBUTE') and an explicit contrast with the sibling find_symbol ('a cross-cutting query that find_symbol (name-only) cannot do'). An agent can distinguish it from find_symbol and find_by_semantics 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?

States when to reach for it and names the alternative it replaces: find_symbol is name-only, this one is attribute-based. Concrete triggers are supplied ('[Obsolete]', '[ApiController]', '[Authorize]', test attributes, '[ObservableProperty]', '[JsonProperty]') and it explains why member scanning is needed when a type/method-only scan misses attributes.

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, but the description goes well beyond them: it explains skipped '+=' cases, XAML markupWires, 'unreleased' semantics, partial types, name collisions, and how empty results should be interpreted. This is unusually rich behavioral context for a read-only analyzer 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 long, but it is front-loaded with purpose and use cases and then organized into return-value, edge-case, and empty-result sections. Given the complexity and absence of an output schema, most detail earns its place, though some sentences are dense enough to verge on over-specification.

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 no output schema, the description carries the full burden of explaining return fields, match limits, sorting, edge cases like markupWires, and how to interpret empty and unresolved results. It is complete enough for an agent to invoke and interpret 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 carries most parameter documentation. The description still adds meaningful semantics, especially that eventName matches exactly and never as a substring, and reinforces test-project exclusion behavior beyond the schema's default-value explanation.

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: find the TYPES that subscribe to a C# event. It distinguishes itself explicitly from find_usages on solution-declared events, so an agent can route 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?

Gives concrete when-to-use cases: 'who listens to this event?', where handlers are wired, and as a leak hint. It also names the alternative behavior of find_usages on solution-declared events and explains how to read empty results, 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 only cover the safety profile (read-only, idempotent, closed-world), and the description adds substantial behavior beyond that: AND combination of filters, whole-value vs substring matching per axis, a 200-item cap with types ordered first, nearMisses surfacing instead of matches, and the zero-match diagnostic logic distinguishing verifiedAbsentAxes from unclassifiedAxes by minConfidence. It also discloses that test-project symbols are matched like production ones, which annotations do not cover.

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 and the one-filter requirement are front-loaded, and the dense diagnostic paragraphs are justified by the tool's complexity and the absence of an output schema. There is some redundancy, such as restating that domain and responsibility are case-insensitive substrings (already in the schema) and a meta-sentence pointing the reader at the parameter lists rather than stating the values.

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 no output schema, the description carries the full burden of describing the return payload (criteria, note, minConfidence, matches with kind/name/declaringType/namespace/matched, plus the conditional diagnostic lists), and it does so completely. It also covers the failure-mode semantics an agent needs to interpret an empty result, which is the main risk for a filter tool of this kind.

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 it by explaining how filters compose (AND), how matched values are attributed per axis with a source ('fact', 'ai', 'inferred', 'none'), and how the echoed criteria encode the match mode ('role=View' vs 'domain~order'). It also clarifies that the enumerated layer/role values live on the parameters themselves and that <ai>-asserted values add their own spellings, which resolves ambiguity the schema alone leaves open.

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 ('Find types and methods by their resolved semantics') and enumerates the four axes (layer, role, domain, responsibility), which clearly separates it from attribute- or side-effect-based siblings. It stops short of naming an alternative tool such as find_by_attribute or find_symbol, so an agent must infer the routing from the axis names alone.

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 a concrete use case ('which types of layer X carry role Y?') and a hard precondition ('At least one filter is required'), plus per-axis guidance on when an axis can never match (responsibility on methods, domain without an <ai> annotation). It does not say when to prefer a sibling tool or what to do if the result is empty beyond interpreting the diagnostic lists.

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 readOnly/idempotent annotations: effect propagation along calls and constructions, the 200-hit cap, methods-only purity listing, unresolved core references causing false PURE reports, test exclusion by default, and rejection of out-of-vocabulary tokens rather than silent zeros. These are exactly the failure modes an agent needs warned about.

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 is front-loaded and every sentence carries information, but the middle paragraphs are dense and nested, with heavy self-quoting ('an empty result reads ...'). Slightly compressed phrasing would improve scanability on a tool an agent may call repeatedly.

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?

No output schema exists, yet the description enumerates the return envelope (scope, effect, purity, methodsScanned, matches, note, availableEffects, testMatchesFiltered) and explains how to read a zero-match result. For a 5-parameter analysis tool 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 coverage is 100%, so the baseline is 3; the description adds real meaning on top by defining what 'unknown' denotes, clarifying that purity='pure' listing is methods-only, and noting that effect combined with purity='pure' is rejected. The includeTests rationale (Seed*/Migrate_* drowning a DB query) also clarifies intent.

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: find code by its side-effect profile, with the closed token vocabulary spelled out. An agent can distinguish this from find_by_semantics, find_usages or calls_external 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 concrete query intents ('what hits the database or the network?', finding pure methods) and explains the default behavior when neither effect nor purity is supplied. It stops short of explicitly naming a sibling tool to use instead, which keeps it from 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/closed-world, and the description still adds substantial behavior beyond them: what the default axis deliberately skips (framework attributes, partial methods, Main, PrintMembers), that nameof in an attribute counts as a call, that designer/generated files are read but never judged, the 200-item cap, and the meaning of the counters and publicApi. Nothing about how the tool behaves 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?

The opening sentence is well front-loaded, but the body is a dense, run-on block with stacked parentheticals and enumerations that repeat schema-level facts (the kinds values are already described in the schema). For a four-parameter tool it is overlong and visually unstructured, even though most sentences carry genuine detail.

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?

There is no output schema, yet the description enumerates the return shape (scope, note, methodsScanned, deadMethods, typesScanned/deadTypes, eligibility counters) and explains the zero-omission rule. Combined with the disclosed exclusion rules and the empty-answer interpretation, an agent has everything needed to call and interpret 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 baseline is 3, but the description adds real semantics: the precise inclusion criteria behind kinds='method', the fact that an unrecognized kinds value falls back to both axes (a behavior not visible in the schema), and the intent of scope and includeTests. That is meaningful added meaning on top of the schema rather than duplication.

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 concrete verb+resource ('List dead-code suspects') and immediately partitions the resource into two named axes with their own definitions. It also positions itself relative to the sibling it consumes ('the reverse type fan-in, the source find_usages reads'), so an agent knows what it is and how it relates to neighboring tools.

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 selection guidance for the main knob: kinds='method' is the default, kinds='type' runs the other axis, kinds='all' runs both, and any other non-blank value runs both. It also explains the empty-result semantics and how to confirm a suspect. It stops short of saying when to prefer this tool over siblings like coverage_gaps or impact_of_change, so it is strong context without full 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 read-only/idempotent/closed-world, and the description adds substantial behavior beyond them: a hard cap of 100 items with a 'truncated' flag, deterministic ordering ('items without via first, then by name'), test implementers excluded by default with a counter, partial-inventory 'note' when core references fail to resolve, and generator hints on empty results. These are exactly the traits an agent needs to interpret results correctly.

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 and the 'use before changing an interface member' line are properly front-loaded, but the middle is a very dense wall of quoted field names and run-on clauses ('via', 'closes', 'through', 'closing') that is hard to parse in one pass. Most content earns its place because there is no output schema, but the packaging could be far tighter.

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 no output schema, the description carries the return-shape burden and does so thoroughly — item fields, ordering, truncation, filter result fields, empty-result hints, and partial-inventory caveats are all covered. Nothing an agent needs to call this correctly or interpret its output 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 meaning on top: interfaceName is case-sensitive, an unreadable closing returns as closing:'unresolved', and the filter outputs (typeArgumentFilter/typeArgumentBaseFilter producing otherClosings, openClosings, familyTypes, leftOut) are explained with examples. The value is real but overlaps the already-detailed schema in places.

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 ('List the types that implement an interface') plus scope (solution or external, e.g. IDisposable), and explicitly positions itself against named siblings: the interface counterpart to get_type_hierarchy and find_overrides. An agent can pick the right one 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 a concrete trigger — 'Use it before changing an interface member, to find every type that must follow' — and names the sibling alternatives for class hierarchies and overrides. It does not state when *not* to use it (e.g. for finding call sites, use find_usages), so it stops short of full routing 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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond that: a hard 100-row cap with a truncated flag, external-BCL bases rendering as '(external base)', declaration-form rendering, and namespace-based row collapsing via mergedNamesakes. It does not mention auth or rate limits, but for a read-only query tool the added result-shaping behavior is substantial.

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 use cases, then alternatives, then return shape - a sensible order with little padding. It runs long for a 2-parameter tool and the final sentence about 'nearest' in empty answers is dense, but each sentence carries distinct information rather than restating structured fields.

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?

No output schema exists, so the description carries the return-shape burden and does so: it names the envelope fields (items, count, totalFound, truncated), the row format, the 100-row cap, the empty-items meaning, and the empty-answer 'nearest' hint. Edge cases (external bases, merged namesakes, qualified names) are all covered.

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 lacks: a qualified name like 'Widget.ToString' matches nothing (schema only says 'simple name'), there is no type filter, and each overload is its own row. It also clarifies that sessionId accepts a recalled session. These are genuine usage constraints beyond the field docs.

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 ('List the override-to-base relationships for methods of a given name') and immediately distinguishes itself from the closest sibling by naming find_implementations and the axis of difference (class inheritance vs interfaces). An agent can tell this apart from interface-implementation and hierarchy tools 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 framings ('who overrides this virtual/abstract method?' before changing a base method; 'what does this override?' for comprehension) and routes to two named alternatives with conditions: get_type_hierarchy for base/derived types and find_usages for callers. 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?

Beyond the readOnly/idempotent annotations, the description discloses important behavior: it reads current files on disk, excludes bin/obj/.vs, works on recalled sessions without refresh_session, only handles string keys, ignores XML-commented markup, and caps lists at 200. It also explains collision semantics and caveats around runtime-assembled keys and library templates, which is unusually rich context for an agent.

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 modes, but it is extremely dense and long, with several run-on clauses covering edge cases and limitations. Much of the detail is useful, yet the lack of structure and the sheer volume make it harder to scan than necessary.

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 a complex tool with no output schema, the description covers the return shape well: definitions with file:line, reference kinds, duplicate handling, conditional count fields, and the full audit-view categories. It also states major limitations and what remains invisible, making it complete enough for an agent to invoke 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 description coverage is 100%, so the input schema already documents key, scope, and sessionId semantics thoroughly. The description reinforces the key/no-key distinction and scope behavior but adds little parameter syntax or format detail beyond what the schema already provides, so the baseline 3 is appropriate.

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: resource-key fan-in across XAML/AXAML markup and C# sources. It explicitly distinguishes the tool from the C# symbol graph by explaining that XAML resources are wired by string key rather than symbol, so an agent can immediately tell what this tool covers that find_usages does not.

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 clearly defines two modes: passing a key to get definitions/references, and omitting it for an audit view of never-referenced keys, collisions, and undefined keys. It also gives strong context about when zero references should be treated as 'verify before deleting.' It does not explicitly name sibling tools like find_usages or find_binding_usages as alternatives, which keeps it from 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?

Goes well past the readOnly/idempotent annotations: discloses ranking order (exact > case-insensitive exact > prefix > substring, then kind order), that the cap never hides an exact match, the 100-item cap, the items/count/totalFound/truncated envelope, the 'nearest' typo suggestion, and the 'generatedSourcesNote'/'note' fields. That is rich behavioral context an agent could not infer from annotations 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?

The core purpose and the 'use before X' routing are front-loaded, but the body is a dense run-on with parenthetical stacking and some redundancy ('a generated property carries a // source-generated note' repeated thematically by the generatedSourcesNote discussion). The ordering, cap, and typo-suggestion facts earn their place; the phrasing around them does not always.

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?

No output schema exists, and the description compensates fully: it names the returned fields (kind, name, declaring type, namespace, signature, project), the envelope shape, and the auxiliary 'nearest'/'generatedSourcesNote'/'note' fields. For a 2-parameter tool with no output schema, nothing an agent needs to interpret results 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 real query semantics beyond the schema — case-insensitive matching, and the non-obvious requirement to search user-defined operators by METADATA name ('op_Equality', 'op_' to list all), plus how enum members must be qualified. The operator naming rule is the kind of thing that would otherwise cause silent zero-hit queries.

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 an enumerated resource set ('Find types, methods, properties, fields, events, enum members and operators whose name contains the query'), then immediately distinguishes itself from find_usages / call_graph / get_context. An agent can tell exactly what class of answer to expect 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?

Explicitly says 'Use this to locate a symbol before find_usages / call_graph / get_context', naming the alternatives and the ordering constraint. It also states the exclusion set (locals, parameters, labels, namespaces, obj/-generated code, .razor-only components), which is a 'when-not-to-expect-results' rule rarely stated this precisely.

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 profile, and the description adds substantial context beyond them: static analysis with no coverage run, a two-hop evidence ceiling, a 50-item truncation cap, and an explicit warning that a 'note' flags misleading cases (name noise, event/enum members, nested types, constructor queries). It even ranks the eleven matchReason tiers by reliability, which is exactly the kind of confidence calibration 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?

Purpose and the coverage_gaps contrast are correctly front-loaded, and most content is load-bearing given there is no output schema. However, the matchReason taxonomy and the trailing caveat sentence are compressed into dense run-ons ('the rest are name guesses', the long list of misleading cases) that are hard to parse in one pass. It is information-rich but over-stuffed relative to what an agent needs before invoking.

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 no output schema, the description carries the return-value burden and does so fully: field names, the truncation cap, the meaning of invokesTotal/dispatchTotal, and the conditions under which 'note' appears. Combined with 100% parameter coverage and annotations for the safety profile, nothing needed to call or interpret the tool 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, but the description adds meaning the schema lacks: symbol matching is case-sensitive, and 'Type.Type' selects the constructor (the schema only mentions the bare and Type.Member forms). It also clarifies that 'Type.Member' scopes to that type's member only. The sessionId parameter is left to the schema, which documents it well.

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 ('Find the tests that likely cover a symbol') and immediately enumerates the detection modes (calls it, reads it, builds it, named after it). It explicitly contrasts itself with the sibling coverage_gaps ('coverage_gaps asks the reverse'), so an agent can route between the two 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 concrete when-to-use conditions on both sides of a change ('before changing a symbol, to see what pins it, and after, to pick tests') and names the complementary tool for the inverse question. It also states the qualifying condition for a hit ('Only a method with a test attribute counts', with the default attribute list), which prevents misuse on non-test code.

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 only say read-only/idempotent; the description adds the substantive behavior: conservative skip-list of untypeable DataContext scopes, what counts as resolved (source-generated, inherited), two concrete measured false-positive classes and their fixes, and the crucial caveat that a hit is evidence to verify, not proof. It also warns that recalled sessions report nothing and that refresh_session is needed after edits.

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 definition and the primary use case, and every block (scope, skip behaviour, false-positive evidence, return shape, freshness) carries distinct information. It is dense — the parenthetical skip-list and the return-shape sentence pack a lot — 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 no output schema, the description takes on return-value disclosure and does it well: count, unresolvedBindings fields, markupFilesScanned/bindingSitesInMarkup as a clean-zero guard, sitesJudged/sitesSkipped/sitesSkippedBy denominator, judgementNote, and nulls on a recalled session. Combined with the caveat that findings need file/line verification, an agent has what it needs to interpret 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 100% and the sole parameter's meaning (session_id from analyze_solution, or an absolute .sln/.slnx/.slnf path) is fully documented in the schema. The description adds only indirectly, via the refresh_session/live-vs-recalled guidance about session state, 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+resource (list silently broken XAML bindings), pins the exact defect class (root member absent on a confidently resolved DataContext), and explicitly distinguishes scope from the two closest siblings (find_binding_usages / find_resource_usages). An agent can tell this apart from those 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 trigger ('use it after renaming or removing view-model members'), a scope boundary ('judges the ROOT member of a binding path only'), and names the alternative tools for the adjacent question. Also states the coverage boundary (WPF/WinUI .xaml, Avalonia .axaml via x:DataType).

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 and non-destructive, yet the description adds substantial context: results vary by resolvedKind, output is capped at 100 with truncation flags, and empty or 'not_found' answers have specific non-obvious meanings (entry points, DI, reflection, generators). It falls short of a 5 only in that a few glossary entries (e.g. 'resourceKeyNote', 'textuallyInvisibleUsers') are named without saying what the agent should do with them.

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 sibling routing are front-loaded, and every paragraph carries actionable content. The middle section is very dense — a long semicolon-delimited glossary of resolvedKind values and optional members — which makes it harder to scan than it needs to be, though it is not padded.

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?

There is no output schema, so the description must carry the return contract, and it does: symbol/resolvedKind/usedBy, the capped envelope with items/count/totalFound/truncated, and the per-item {name, file, line} shape including the caveat that line is the declaration site. With a complex, kind-dependent result set, this level of detail is what the agent needs.

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 3 is the baseline; the description exceeds it by explaining the naming rules for `symbol` beyond the schema's phrasing — bare names answer for exactly one kind, chosen by a stated precedence and unioned across namesakes. It does not re-explain includeTests, which the schema already covers well.

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 opening sentence gives a specific verb and resource ('List who uses a symbol: its direct fan-in') and immediately disambiguates from the two nearest siblings: impact_of_change (closure + risk) and calls_external (external members). An agent can select 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?

It states the triggering situation ('before changing or deleting a symbol') and explicitly rules out the naive alternative ('not grep'). Combined with the named sibling alternatives for transitive impact and external members, the when/when-not decision is fully resolved.

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 substantial non-obvious behavior: the 8000-token budget floor, the two-way budget compaction, that the seed is never dropped and degrades to STRUCTURE, disclosure comments for dropped types, and Multi-TFM dedup keeping the NEWEST TFM's instance.

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 in the first sentence, then routing. The routing paragraph is long and slightly dense with parentheticals, but each clause carries actionable routing or behavioral information rather than 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?

There is no output schema, yet the description explains the return shape (AI-Builder-Markdown, kept legends, dropped sections, optional QUALITY_HOTSPOTS) and the constraints that govern it. 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% and the parameter docs are already rich, but the description still adds decision value beyond the schema, e.g. when to pass includeQualityMetrics (reviewing quality / picking refactor targets) and the practical meaning of omitting budget versus tightening it.

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 dense, token-budgeted Markdown slice of the code around a symbol, including its depth-1 neighborhood. It also explicitly differentiates itself from export_markdown (whole solution) and explain_symbol (chosen environment), so an agent can pick it apart from siblings 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 explicit routing: prefer over export_markdown for a single symbol, use explain_symbol for callers/tests/implementations/quality, use pack_for_task or prepare_task for whole-task bundling. It also states the prerequisite (use find_symbol first to disambiguate).

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 far past the annotations: no analyzer runs (SDK's included), loadable source generators do run, 200-item list cap while counts cover the full set, multi-target dedup, #pragma exclusions, live-session requirement with recalled sessions rejected, and a bulleted disclosure list (incompleteProjects, cascadeFromIncomplete, generatedCodeGaps, designTimeBuildFailures, suppressors) explaining how to read each field, including the warning to treat suppressedDiagnosticsTotal as a magnitude not a ratio half.

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 and call ordering, then structured into return shape and a bulleted caveat list. It is long, and portions (scope substring matching, severityFloor 'auto' behavior) restate the schema almost verbatim, but nearly every sentence carries distinct 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?

There is no output schema, so the description carries the full burden of explaining return values — and it does: verdict, projectsScanned, errorCount/warningCount/infoCount, the diagnostics item shape, the listing-vs-counting asymmetry, and the meaning of each disclosure field. Nothing needed to interpret the result 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 adds genuine meaning beyond it: 'It filters the ANSWER, not the work: every project is compiled either way,' and the note that suppressors are solution code executed inside the server (pointing at SECURITY.md). Some of the scope/severityFloor text duplicates the schema descriptions, which keeps this below 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+resource+mechanism: 'Compiler errors and warnings without a build: every C# project of the session is compiled in memory, in seconds.' It also explicitly distinguishes itself from the nearest sibling, list_insights, which 'reports design findings instead.'

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 ordering ('refresh_session, THEN this'), the reason (diagnostics come from the session snapshot, not disk), the behavior when stale, and the exception for builds vs restores (refresh_session(force: true)). It also names the alternative tool for a different class of question.

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 substantial behavior beyond them: the default 20-item cap and '(... and N more)' remainder marker, the error contract for unknown ids (rejected WITH the known producer ids), the 0-findings reporting case, and the triage-filtering semantics where 'suppressedDetailCount' sums suppression + dismissal counts and is absent when zero. None of this is derivable from the 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 the core action and the discovery route, and every sentence carries operational information. It is dense to the point of heavy nesting (multiple stacked parentheticals in the triage sentence), which costs some readability, 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?

No output schema exists, so the description carries the return-shape burden and does so: it describes the Details list, the truncation marker, and 'suppressedDetailCount' presence/absence semantics. For a 4-param read tool with annotations covering safety, nothing needed to invoke or interpret the call 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, but the description adds real meaning: insightId is characterized as producer-level with a concrete example shape, maxDetails is framed as call-scoped with an explicit drill-down intent, and dbPath is condensed to a reference ('same semantics as list_insights') rather than restated. It stops short of 5 because much of the dbPath/maxDetails text parallels the schema wording.

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 with scope: 'Get the full detail of one insight ... by its id', and explicitly names the payload ('incl. the per-item Details list'). It distinguishes itself from the sibling list_insights ('the producers that found issues') so an agent can route correctly 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?

Names the discovery path explicitly ('Discover ids via list_insights'), explains the when-not edge case (a registered producer with 0 findings is not discoverable via list_insights), and gives concrete conditions for the optional params (pass maxDetails for a full drill-down, pass dbPath for DB-scoped thresholds). Alternatives and their selection conditions are 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 cover readOnly/idempotent/non-destructive, but the description goes well beyond them: a capped envelope (items, count, totalFound, truncated; max 100), transitive derivedTypes semantics, external-base naming, the not_found contract, and refresh/restore caveats. These are behaviors an agent cannot infer from the 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?

Front-loaded correctly: purpose first, then return shape, then edge cases, then the not_found contract. It is long and dense, but with no output schema most of the return-value detail is load-bearing rather than filler; a few clauses (arity-qualification, '[Project]' marking) push toward over-explanation.

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 no output schema and a conceptually complex return, the description fully specifies the response fields, the truncation limit, ordering rules, namesake merging/separation, and the three-empty-list not_found behavior. Nothing an agent needs to interpret or call the tool 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% and both parameters are already documented in the schema (case-sensitivity, arity suffix, session_id sourcing). The description nonetheless adds meaning beyond the schema: a bare name merges a generic with its non-generic namesake and 'mergedArities' signals it, plus the recalled-session requirement.

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 opening sentence gives a precise verb+resource: 'Walk one type's inheritance in both directions' naming baseChain, derivedTypes and declared interfaces. It explicitly differentiates from siblings, calling itself the type-level counterpart to find_overrides and directing interface-implementation queries to find_implementations.

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 a concrete situation ('Use it before changing a base class') and names two alternatives with the condition that selects them (find_overrides for overrides, find_implementations for interface implementers). When-to-use and when-to-use-something-else are both explicit.

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 'Read-only.' adds nothing; but the description contributes genuinely non-structured behavior: how risk maps to productionImpactCount thresholds, saturation overriding counts on cycle-dominated closures, 'riskBasis'/'implementers' appearing for interface and abstract symbols, and 'note'/'collision'/'not_found' edge states. The disclosure is rich but so compressed and jargon-heavy that an agent must parse it repeatedly to act on it.

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 call-it-first rule are correctly front-loaded, but the body degenerates into a dense wall of single-quoted field names and per-kind clauses that are hard to scan and partly redundant with each other. Several sentences ('registration', 'serializers', 'attachedProperty' trail, moving no count) pack multiple concepts into one line at the cost of readability.

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?

There is no output schema, so the description carries the return-value burden entirely, and it does: it names every count and risk field, explains what each counts and excludes, and covers degenerate results such as zero direct counts, all-test solutions, unresolved references and name collisions. For a tool of this complexity, an agent has enough to interpret the response 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 both parameters already document case sensitivity and the Type.Member form, so the baseline applies. The description nevertheless adds resolution meaning: a type by simple name, a member bare (implying single kind) or qualified, and that constructors must go elsewhere. The sessionId handling is left entirely to 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: 'Estimate the blast radius of changing a symbol' and enumerates the output dimensions (direct users, dependents, risk level). It separates itself from find_usages by framing itself as the pre-edit decision tool rather than a usage listing.

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: 'Call it first, before any edit to a symbol other code names (a rename, signature, default value)', plus the rationale that a compile checks names, not consumer assumptions. It also routes a specific case out to a sibling: constructors ('Type.Type') should use find_usages, and points to find_usages for resolution semantics.

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/idempotent/non-destructive, and the description goes well beyond them: it writes no configuration, no DB row, marks nothing initialized, walks the warm session workspace without re-analysis, and requires a live session because a recalled one is rejected with an error. That is exactly the 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-loaded with step 1 of 2 and the when-to-use conditions, and the return-value detail is necessary because no output schema exists. It is dense and the return paragraph runs long with semicolon-chained clauses, but no sentence 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 no output schema, the description fully specifies the return shape: solutionPath, declaredNamespaces vs referencedNamespaces, capped envelope semantics with max 300, generatedDocuments/globalUsing caveats, frameworkApiAreas with keepRule guidance, and proposalFormat. It also tells the agent how to consume the result ('Propose a mapping from the returned material'), including the critical rule never to exclude the solution's own namespaces.

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 sessionId description already covers the .sln/.slnx/.slnf path fallback, so the schema carries most of the load. The description still adds a constraint the schema lacks: the session must be live, and a recalled session errors out, which materially narrows acceptable sessionId values.

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 ('Collect the raw material for the guided setup of a solution's Layer Profile, Exclude-Namespaces and Test Profile') and explicitly frames itself as step 1 of 2 with apply_solution_config as the writer. That makes it unmistakable against its closest siblings, apply_solution_config and solution_config_status, 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?

Names the exact triggering conditions (solution_config_status or the configInit hint of analyze_solution reporting an axis as not initialized, or check_solution_config_drift reporting one as stale) and the follow-on call ('then call apply_solution_config with it'). It also gives an explicit not-for-this alternative: 'To only see what is configured, use solution_config_status.'

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=true, and the description adds substantive context beyond them: the exact write footprint, the containment rule (only inside the session's own solution directory), the non-destructive default that force overrides, and the operational requirement to restart the client and then call refresh_session so the guard stops being reported missing.

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 the write footprint before the operational caveats, and every clause carries information. The single dense paragraph is slightly heavy, but there is little that could be cut without losing routing or safety detail.

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 installer with no output schema, the description covers the write scope, the safety default, the containment boundary, and the post-install recovery step. It stops short of describing failure modes (e.g. what happens if sessionId is unknown or the harness is unsupported), but nothing critical 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 all three parameters are already documented, including the harness enumeration values and the force overwrite semantics. The description largely restates the schema's 'omit harness' and 'kept unless force=true' behavior rather than adding format or edge-case detail, so the 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 (install), resource (the aicb symbol guard), and precisely scopes what is written: the guard script plus one harness wiring entry, explicitly excluding .mcp.json and skills. It even names the concrete target files (.claude/settings.json, .codex/hooks.json, opencode.json), so the agent can distinguish it from every sibling at a glance.

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 clear usage conditions: omit 'harness' to target the calling harness, existing guard/wiring is preserved unless force=true, and it names the follow-up sequence (restart/reconnect, then call refresh_session). It does not explicitly contrast against sibling config tools like apply_solution_config or init_solution_config, so it stops short of full 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 mark it read-only and non-destructive, and the description adds substantial behavior beyond that: it defines 'created' vs 'injected', explains attribution of field/property initializers to '.ctor'/'.cctor', notes that Lazy<X> is attributed to the outer type and arrays do not count, explains test-project inclusion, return ordering, 200-item cap, and what a 'note' and 'nearest' mean. No contradictions with 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?

The description is long, but the complexity of the tool justifies most of the detail. It is front-loaded with purpose and usage, then moves into behavioral definitions and return semantics; the density is high but most sentences convey necessary edge-case 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?

With no output schema, the description carries the return-value burden and does so thoroughly: it explains the response fields, counts, site ordering, 200-item limit, test-project flags, and the special meanings of 'note' and 'nearest'. It is complete for an agent to invoke and interpret the 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 schema already documents all three parameters. The description adds extra semantic nuance beyond the schema: typeName matching on simple name, dropping namespace and generic arguments, unioning namesakes, accepting external types like 'List', and clarifying that scope applies to the SITE's namespace.

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: 'Find where a type is constructed and where it is injected.' It explicitly distinguishes itself from find_usages ('every reference') and resolve_injection ('what is registered for a type'), 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 concrete when-to-use guidance: 'Use it before changing a constructor, and to see whether anything but a test builds a type.' It also names the alternative tools and the precise question each answers, making the routing decision explicit.

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 only cover the safe-read profile, and the description adds genuinely non-obvious behavior: results are triage-filtered on two axes (intentional suppressions in DB or .aicb.json sidecar, plus user dismissals in the solution record only), fully-filtered insights vanish, and 'suppressed' merges both axes. It also warns that 'title' is computed pre-filtering and that remediationCostMinutes is a coarse fixed-rule estimate, which prevents real misinterpretation of the output.

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 and triage-filtering caveats are front-loaded, but the paragraph is a dense run-on that repeats the files-parameter semantics almost verbatim from the schema and stacks precedence rules mid-sentence. Signal is high, but several clauses (the sidecar-vs-dismissal aside, the title caveat) could be tightened without losing meaning.

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 no output schema and a non-trivial return shape, the description carries the burden well: it explains the solution-wide array versus the {files, notInSolution, insights} object, what detailsCount, suppressed and remediationCostMinutes mean, and the pre-filter title caveat. An agent has enough to call it and interpret results 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 baseline is 3; the description still adds value by explaining the precedence consequences (an explicit analyze_solution(layerProfile) wins over the DB-configured profile, matching solution_metrics and the CLI gate) and the session's test-detection profile. The files-parameter prose largely restates the schema's own long description rather than extending it.

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 ('List code-quality / async / design-smell insights for a session') and enumerates concrete finding kinds (long methods, fat interfaces, unused types, missing async suffixes). It also positions itself against the sibling that drills in: insights are aggregated per producer and get_insight lists the detail lines.

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 clear conditional guidance for the optional inputs: pass dbPath to use that DB's active QualityProfile, omit it for the DB-free default; pass files for findings about types a change touches. It does not spell out when to prefer this over sibling diagnostics tools (get_diagnostics, find_dead_code, architecture_overview), only implying the get_insight split.

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 safety bar is low; the description instead adds real behavioral context — the --db-path prerequisite and the fact that profile selection is immutable at runtime. Null-handling rules (null templateId, null tokenBudget means inherit through template then active PipelineProfile) are disclosed, though some of this drifts into return-shape territory rather than 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?

The purpose is front-loaded, but the body is a single sprawling sentence with stacked parentheticals and an ALL-CAPS 'AND' joining two unrelated payload descriptions (identity fields vs. render config). Splitting the return-field inventory from the usage note would make it far more scannable.

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?

There is no output schema, so the description carries the burden of explaining the return shape — and it does, field by field, including null semantics and the two toolSelection encodings. Combined with the stated prerequisite and the 'no runtime switch' constraint, an agent has everything needed to call and interpret this 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter guidance because none is needed.

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 ('List the MCP profiles in the server's config DB') and enumerates the exact fields returned. No sibling tool in the list covers MCP profile configuration, so it is unambiguously distinguishable.

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 prerequisite ('Requires the server to be started with --db-path') and explains what to do with the results ('Use the ids with aicb mcp --mcp-profile <id> to pin the profile at server start'). It also pre-empts a fruitless search by stating there is no runtime switch tool. It never frames when to call this versus another tool, but no viable alternative exists.

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, closed-world, non-destructive), so the bar is lower. The description adds genuinely useful behavior: by default per-tool descriptions are omitted for cheapness, detail="full" includes them, and no session is needed.

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 intent is front-loaded ('capability map'), but the body is one very long sentence with deeply nested parentheses enumerating pool states and sections, which hurts scannability. It is information-dense but not efficiently structured.

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?

There is no output schema, so the description carries the burden of describing the return shape, and it does: three pool-state lists, the navigation CORE, task FACETS, guidance styles, and legacy bundles. Nothing needed to call or interpret the result 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% and the single `detail` parameter is fully documented in the schema, so baseline is 3. The description reinforces the lean-vs-full tradeoff and its cost rationale, but adds little format or syntax detail 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 - an index naming every tool the server has - and even enumerates the three pool groupings it returns. It distinguishes itself from the similar-sounding list_mcp_profiles and list_insights by describing a capability map rather than profiles or insights.

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 cases: discovering specialized long-tail tools (name examples) and checking whether a wanted tool is merely in outOfPool rather than nonexistent. It also explains the alternative paths (an MCP profile that names the tool, or the AICB_MCP_TOOLS override).

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), but the description adds substantial context beyond them: it does not reduce query execution cost, it costs ~50 tokens instead of the full answer, it enforces a 16-query cap, it follows the active pool, and it refuses the same tools as batch for four named reasons. The only minor gap is that it doesn't detail per-item failure semantics beyond 'the refusal message names which one applies'.

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?

Dense and front-loaded – the core 'token count without the answer' claim and the decide-then-call usage rule come first, followed by mechanics. It is long, and the 'Max 16 queries per call' statement duplicates the schema description, but nearly every sentence carries information an agent needs.

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?

There is no output schema, yet the description fully specifies the return payload ({tool, ok, tokens, chars, returned, totalFound, truncated, budgetNote}) and explains the semantics of the ambiguous fields, including how budgetNote surfaces prose-level budget pruning. An agent has everything needed to call and interpret this 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 goes further: it clarifies that sessionId is shared once and must NOT be repeated inside each query's args, describes the {tool, args} item shape, and supplies a worked example with real args. That is meaningfully more than the schema provides.

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+resource: it reports the exact token count of a read-only query's answer without returning it. It explicitly distinguishes itself from sibling batch ("Same shape as batch") and from the actual answering tools it prices, so an agent can route correctly 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 concrete when-to-use conditions (decide whether a call is worth making, what budget to pass get_context/explain_symbol/pack_for_task, whether to narrow scope first) and an explicit when-not ("measure to DECIDE, then call once - do not measure every call by reflex"). It also explains what it refuses and why, which is strong alternative-routing 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 safety profile (readOnly, idempotent, non-destructive), and the description adds substantial non-obvious behavior: the 8000-token budget floor, two-way budget enforcement (body compaction plus dropping least-relevant non-seed types), pinned exact names, a dropped-types comment, multi-TFM dedup to the NEWEST TFM, and the default ~10000-token ceiling.

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 in the first sentence, then progressively narrower detail. It is dense and on the long side, with some parenthetical tangents (the 'slot' alias, the profile-token-budget aside), but nearly every clause carries actionable 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?

No output schema exists, and the description compensates by describing the return shape (lean vs full AI-Builder-MD, PATH/COMPRESSION legends, quality hotspots section), so an agent knows what it will receive. Combined with the routing to prepare_task and the session/prerequisite context, nothing essential 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 genuinely enriches it: the goal's symbol-matching semantics (exact names suppress other words; segment matching for 'cancel order' -> CancelOrder), the lean default's effect on preamble/sections, and budget's dual enforcement. Only the facet enum values are left entirely to 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 precise verb+resource: 'Goal-driven context packing' that seeds on goal-named symbols, expands the neighborhood, and returns a token-budgeted Markdown bundle. It explicitly distinguishes itself from the closest sibling by routing edit-ready/template work to prepare_task.

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 conditions (name symbols in the goal to steer seeding; use prepare_task for an EDIT-ready or template-shaped bundle; set includeQualityMetrics for refactor/quality passes). Alternatives and exclusions are named rather than implied.

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, but the description goes well beyond them: return format is text not JSON, the leading manifest comment reveals coverage and gaps ((none)), staleness precedes it after a source edit, multi-TFM solutions dedupe to the newest TFM, and tight budgets drop neighborhood/tests/siblings with a leading note naming the drops. It also documents the never-dropped guarantees for named types and single method owners.

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 correctly, with purpose first and usage routing second. However it is long, and substantial portions (the template vs lean render path, facet trailer, budget behavior) duplicate the parameter descriptions already present in the schema, which is padding for a reader who has 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?

There is no output schema, so the description must carry the return-value burden and does: it explains the manifest comment, staleness line, render/template/lean distinctions, and the text-vs-JSON format. For an 8-parameter, complex bundle-builder, 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 adds real meaning beyond the schema: the precise drop order under a tight budget, the never-drop rules, the fact that lean/includeQualityMetrics act only on the lean render path, and the interaction between budget and the profile/template ceiling. These cross-parameter behaviors are not 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?

Opens with a specific verb+resource: 'Build an EDIT-ready context bundle for a task goal', then enumerates exactly what the bundle contains (symbol source, dependency neighborhood, covering tests, convention siblings). It actively distinguishes itself from siblings by naming pack_for_task, get_context, explain_symbol, and review_context with the conditions that separate them.

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: 'Prefer this over pack_for_task when you're about to EDIT, not just read', 'For one symbol use get_context or explain_symbol', 'for blast radius and test coverage as numbers use review_context'. Both when-to-use and when-not-to-use are stated, with alternatives 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 only declare readOnly=false/idempotent=true/destructive=false; the description goes far beyond by disclosing the W0 file-set-hash fast path, timestamp-vs-text comparison, assets-file restore detection via MSBuild, the one-shot auto-retry after an unresolved-reference build, warm-workspace reuse, and the observable-side-effect warning that the incremental path can silently stop engaging. Consistent with annotations (a state-mutating but idempotent cache refresh).

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 stale-graph warning, and nearly every clause carries operational information. It is dense and long for a single paragraph, with nested parentheticals ('a silent source of wrong results', the timestamp caveat) that take effort to parse but are not padding.

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?

No output schema exists, and the description compensates by naming the return shape { changed, reason, session, mode } and explaining how to interpret 'mode' including its absence and the silent-degradation symptom. For a 2-parameter tool with annotations, nothing an agent needs in order to call or interpret it 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 marginal meaning by framing force as the deterministic override and explaining why an ordinary call can legitimately answer 'unchanged' in the restore/build case. Most of this overlaps the schema's own force description, so it does not clear the bar for 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 ('Re-analyze the session's solution after YOUR code edits') and immediately contrasts its role with named siblings (find_usages / impact_of_change / list_insights / get_context) that go stale without it. An agent can tell exactly what this does and why it exists.

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 ('once you have changed .cs files'), an explicit consequence of skipping it (stale pre-edit graph), and explicit guidance on the force alternative ('force' is the deterministic way to demand a reload; leave false for the normal after-an-edit refresh). It also pre-empts false positives (save without edit, plain build) so the agent knows when a no-op result is legitimate.

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/non-destructive, and the description adds substantial context beyond them: exactly which registration forms are read vs. skipped (descriptor built elsewhere, AddHttpClient helpers, Scrutor, other containers) and what an empty result means. It is dense and useful, though some phrasing is ambiguous enough to slightly muddy the behavioral picture.

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 exclusions are well front-loaded, but the body is a wall of dense, fragmented sentences with heavy parenthetical nesting ('A key, and a closing, is a service of its own'). Given the tool's complexity some density is warranted, yet several clauses repeat schema content and could be trimmed.

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 no output schema, the description carries the full burden of explaining the returned JSON and does so in detail (registrations fields, ambiguous, effectiveRegistration, consumer counts, empty-result reasons). It also covers test filtering, making it nearly complete for a complex tool, only undermined slightly by the phantom parameter name.

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 interface/sessionId/site/includeTests thoroughly, and the description's interface explanation largely restates it. It also references 'typeArgumentFilter', which is not an actual parameter in the schema, adding confusion rather than meaning.

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 gives a specific verb, resource, and scope ('Resolve a Microsoft DI or MEF registration: what is registered for a service, with lifetime and site') and immediately names the three siblings it is not (find_usages, find_implementations, instantiation_sites). An agent can distinguish it from neighbors 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 exclusions route the agent: usage vs. implementers vs. construction each map to a named alternative tool. It also states the includeTests toggle's effect and the empty-list semantics ('never not registered'), which function as usage rules.

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 (read-only, idempotent, non-destructive), yet the description adds substantial behavioral detail: results are ordered by symbol NAME and indexed by 'symbol' rather than request position, the 50-row cap and its retention policy, invokesTotal/dispatchTotal semantics, 'not_found' handling with notes, union counting for shared bare names, and test doubles included. Very little about runtime behavior 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?

Purpose is front-loaded and nearly every sentence carries unique semantics (ordering key, cap policy, count attribution, namesake caveat). It is, however, a dense unformatted block without headers or bullets, which makes the return-shape details harder to scan than they need to be given the volume.

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 no output schema, the description carries the full burden and does so: every returned field (symbol, resolvedKind, directUsages, transitiveImpact, risk, implementations, coveringTests and its subfields, coveringTestsTotal/Truncated) is documented along with edge cases like not_found and unioned counts. Nothing an agent needs to interpret the response 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 goes beyond it by stating that symbols must not be empty and that it accepts the exact strings find_usages resolves (a type's simple name, or a member bare or as Type.Member). It does not elaborate on sessionId beyond what the schema already documents.

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+scope ('Assemble review context for a set of changed symbols in ONE call') and enumerates exactly what is bundled: fan-in, transitive impact with risk level, implementers, covering tests. It explicitly names the four siblings it consolidates (find_usages, impact_of_change, find_implementations, find_tests_for), so an agent can place it precisely in the toolset.

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 triggering situation ('Use this before reviewing or refactoring to see blast radius + test coverage at a glance') and gives explicit exclusions with routing alternatives: it does not name callers (use find_usages or impact_of_change) and returns no code (use explain_symbol). When-to-use, when-not-to-use, and alternatives are all present.

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 the write target: the aicb DB, not source or configuration. It explains exactly what is added, that a missing DB file is created, that nothing is overwritten, that every call adds a fresh snapshot id, that name is a label rather than a key, and that recalled snapshots report lineNumbersAvailable false.

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 usage, then return values, write behavior, and parameter nuances. Although detailed, every sentence carries operational information for a stateful snapshot tool.

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?

There is no output schema, but the description lists the JSON return fields and explains the persistence semantics. For a non-idempotent DB-writing tool, the description is complete enough for an agent to decide when and how to call it.

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 still adds useful meaning: sessionId may be a live or recalled session id or an absolute solution path, and omitting dbPath uses the server's standard config DB unless none was resolved, in which case the call fails with 'dbPath is required'.

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: persist the current session's analyzed model as a named Manual snapshot in an aicb DB. It also names the sibling tool used afterward, compare_with_previous, so the agent can distinguish this from diff/compare tools.

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 use this before a bulk mechanical change and call compare_with_previous afterwards. It also states that ordinary edits need no snapshot because git diff and tests cover them, giving a clear when-not-to-use condition.

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 substantial beyond-schema context: no session required, plain-text rather than JSON return, that it reads the config DB schema version and shells out to git in the analyzed repo, and that analyzer drift is silent without a session. It also discloses a real limitation ('a new parameter on an existing tool is not detected') so the agent knows the boundary of the check.

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 identity and the recommended call point before any drift detail, and each drift paragraph pairs a symptom with an action (rebuild, re-save, restart, migrate). The drift block is dense and heavy on parentheticals, running longer than a no-parameter tool strictly requires, but almost every clause carries distinct diagnostic value.

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 no output schema, the description takes on the full burden of explaining the return value and does so precisely: line 1 format, the literal 'Config DB schema: user_version=N' line, the omitted-commit case, and each conditional drift section tied to a remedy. Everything an agent needs to call and interpret the result is present.

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?

Zero parameters with an empty object schema, so there is nothing for the description to disambiguate; the baseline applies. The space it would spend on parameters is instead spent on interpreting the return payload, which is the more useful investment here.

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