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

Annotations only supply boolean hints; the description explains the non-read-only hint by disclosing that MSBuild design-time builds can write generated files under obj/, that sources are read as-is on disk, and that the model lives in server memory (90-minute idle TTL, max 8 sessions). It also adds cost/latency context (minutes on large solutions, progress token) and the non-idempotency rationale (a second call is a full reload into a new session), which is exactly the context the hints alone 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?

Front-loaded with purpose, then call-avoidance, return shape, edge-case flag, behavior, and parameters in a sensible order; each paragraph carries distinct information. It is dense and long for a 3-parameter tool, with some clauses (the incompleteRun and configInit passages) that take effort to parse, but little is genuinely redundant with the 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 correctly enumerates the returned JSON fields, flags which are conditional (analyzePreferredTfmOnly, incompleteRun, configInit, agentWiring) and warns that an absent incompleteRun is not an all-clear, routing the agent to get_diagnostics. For an entry-point tool with three-way config resolution this is complete enough to call 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 decision guidance beyond the schema: 'normally pass only solutionPath' and the per-axis precedence chain (config DB > committed .aicb.json > built-in heuristics), plus the scoping note that layerProfile overrides only the layer axis. It largely consolidates what the verbose schema descriptions already say, which keeps it short of a 5.

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

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

States a specific verb and resource ('Analyze a C#/.NET solution (.sln, .slnx or .slnf) with Roslyn') and pins its identity as 'the entry point of this server', explicitly contrasted with refresh_session and with the tools that accept sessionId. An agent can place it among 50+ siblings without opening a schema.

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

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

Gives explicit when-not guidance ('Calling it is optional... do not call it just to run a query'), explicit when ('Call it to read this answer first or to pass layerProfile / dbPath'), and names the alternative for the edit case ('After editing .cs files call refresh_session, not this'). Nothing about selection 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 declare destructive/not-readOnly/not-idempotent; the description goes well beyond by disclosing dual writes to the DB and the git-tracked sidecar (with sidecarPath and a commit recommendation), refusal-before-write semantics for malformed or locked sidecars, a warning path when the file becomes unreadable mid-write, and keep-rule relocations between 'exclusions' and 'keepNamespaces'. It also states validation behavior (invalid matchType rejected, non-boolean keep flag rejected).

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 first sentence front-loads the action well, but the remainder is one very long unbroken paragraph mixing core behavior, JSON examples, and edge-case error handling. Some JSON example content duplicates what the schema property descriptions already show for testProposalJson, so a portion of the text does not earn its place.

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, dual-target write tool with nine parameters and no output schema, the description covers what an agent needs: what gets created and activated, where it is written, the returned sidecarPath, the commit obligation, and the failure modes that abort or partially succeed. The remaining gaps (naming parameters, layeringPolicy) are fully carried by the schema.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description genuinely adds meaning the schema lacks: literal JSON shapes for proposalJson and testProposalJson, the matchType value set (Contains|StartsWith|EndsWith|Exact) even though no schema enum exists, the fact that test rules match PROJECT names, and the keep/keepNamespaces semantics. Only the naming parameters (layerProfileName, exclusionListName) and layeringPolicy get no extra treatment.

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: it applies a proposed layer/exclusion/test configuration and creates plus activates the corresponding profiles and sidecar entries. The scope (DB + git-tracked <SolutionName>.aicb.json, slots marked initialized) is concrete. It never names a sibling such as init_solution_config or check_solution_config_drift to draw the boundary explicitly, so it falls short of a 5.

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

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

It gives operational rules for using the tool correctly (at least one axis must be non-empty, testPreset is mutually exclusive with testProposalJson, an axis not named retains the existing sidecar value), which implies when it is applicable. However, it never says when to prefer this over siblings like init_solution_config or solution_config_status, nor does it state prerequisites or exclusions relative to alternatives. Usage is inferable but not routed.

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), so the description is free to disclose traits the annotations cannot: the LEADING <TRUNCATION> block and how to read it, the 80-entry-per-section cap with '+N more' rows, the 2000-type layer-map ceiling, multi-TFM deduplication to the newest TFM, and degraded behaviour on recalled sessions. That is genuinely useful context beyond structured fields.

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

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

Front-loaded with the single most important fact (whole-solution orientation, bounded output) and organized with emphatic labels (BOUNDED AT SCALE, PRODUCTION-FOCUSED, Recall-safe). It is dense and parenthetical-heavy, with some restatement of schema-level guidance, but little of it is wasted.

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

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

No output schema exists, so the description carries the burden of describing the return shape and does so in detail: truncation block semantics, section list, domain summary, quality-hotspots contents, and what is absent. Combined with the token-cap and capping behaviour, an agent has everything needed to call it and interpret 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 description coverage is 100%, so all four parameters are already documented in the schema, including the same rationales for lean/includeTests/summaryOnly. The description mostly restates those defaults and conditions rather than adding new syntax or semantics, so the baseline 3 for schema-carried parameters 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?

States a specific verb and resource ('Orient on a whole solution', 'Renders a structural-only AI-Builder-Markdown overview') and enumerates exactly which graphs are included and which are deliberately not (no per-type/per-file source blocks, no method-level call graphs). It explicitly distinguishes itself from siblings export_markdown, call_graph, explain_symbol and get_context.

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: 'Use this FIRST to understand a codebase's shape, then get_context / explain_symbol to drill into a symbol.' It names alternatives with the condition that selects them (export_markdown for the full set, find_symbol/call_graph/get_context to drill in, includeTests for test projects, summaryOnly for 200+ project monoliths).

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 already declare the safe read-only/idempotent profile, and the description adds substantial context beyond them: the 500-edge cap with a truncated flag, cycle-safe traversal, edge key format, and the critical name-resolution behavior (every same-named declaration is a root, unioned together). This is exactly the kind of behavior an agent cannot infer from annotations.

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

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

Front-loaded with purpose, then progressively adds depth-limit, truncation, and root-resolution caveats. Dense but every sentence carries information; only the length keeps it from a 5.

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

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

No output schema exists, so the description must cover return values, and it does: (caller, callee) edges, lookup keys, cycle safety, truncation flag, and the 'rootedAt' diagnostic. Complete enough for an agent to call 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 the baseline is 3, but the description adds real meaning: it explains the semantic difference between direction values and, crucially, that 'method' resolves to all same-named declarations rather than one symbol, which materially changes how the parameter should be chosen.

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 ('Build a depth-limited call graph rooted at a method NAME') and immediately distinguishes direction modes ('callees' vs 'callers'). An agent can tell exactly what this produces 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 clear operational guidance: which direction to choose, and what to do when the result is too big (re-query a rarer name) or when 'rootedAt' is empty. It does not explicitly name alternative sibling tools (e.g. find_usages, impact_of_change) for comparison, so it stops short of full when-not 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 cover only safety (readOnly/idempotent/non-destructive), but the description goes far beyond: it defines the scanned units (methods, accessors, constructors with bodies under metadata names), declares the open vocabulary with no did-you-mean, warns that empty is a strong but not absolute statement, and enumerates exactly what is NOT recorded (field reads, bare constructors, operators, indexers, event subscriptions, compiler-lowered calls).

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 usage scenario are front-loaded, and the dense caveat list is justified by the tool's many non-obvious edge cases. It is long and could be tightened, but nearly every sentence carries operational 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 envelope (scope, pattern, methodsScanned, matches, 200-hit cap sorted not ranked, testMatchesFiltered, the note field) and the per-hit structure (name, declaringType, namespace, matchedCalls, matchedReads).

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 pattern is a case-insensitive substring of the whole key including the parameter list, that type names also hit units merely passing that type, that broad patterns truncate at 200, and how testMatchesFiltered relates to methodsScanned.

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+scope ('Find the code that calls an EXTERNAL member - BCL or package - whose key contains a pattern') and explicitly differentiates from siblings, noting find_usages covers solution symbols only and find_by_side_effects classifies the same calls into effect tokens.

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 scenarios ('who calls the risky or external API X?': AOT/trimming readiness, security surface, dependency footprint) with concrete example patterns, and names the alternatives (find_usages, find_by_side_effects) that answer different questions.

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, non-destructive; the description adds genuinely new behavior: it changes no configuration, creates no solution row, refuses a nonexistent dbPath with an error, upgrades an older DB on open, judges the config a plain analyze_solution resolves now, and requires a live (not recalled) session. The only gap is no note on performance or rate characteristics, but the behavioral surface is well covered.

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 question and the sibling contrast before the details; every sentence carries information. It is dense and long, but the length is justified by the absence of an output schema and the non-obvious dbPath precedence rules.

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 (layer/exclusion/test axes, source/name/status/stale/considered/sample/reason fields, status thresholds, built-in-preset and not-configured semantics, sidecarProblem). 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% (baseline 3), but the description adds decision guidance beyond the schema: 'normally pass only sessionId' and pass dbPath only if the session was analyzed with that same dbPath, otherwise the judgment is meaningless. That is real added meaning, not a 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?

States a specific verb+resource ('Check whether a solution's active Layer Profile, Exclude-Namespaces and Test Profile still FIT the code') and explicitly differentiates from the sibling solution_config_status by contrasting 'which config is active' vs 'does it still fit'.

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 triggers ('a solution configured a while ago, or when layer or exclusion results look off'), an explicit exclusion ('Do not use it on a never-configured solution: nothing is evaluated there'), and names the remedial siblings init_solution_config and apply_solution_config.

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/openWorld=false), and the description adds real behavioral detail on top: the exact return shape (added/removed types, per-type added/removed methods and signature changes), the dbPath default, and the important limitation that the diff is name-based and syntactic with no method-body diff.

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?

A single dense paragraph that front-loads the core purpose before defaults, filtering, return shape and the syntactic-only caveat. Every sentence contributes, though the block is information-heavy and could be 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?

With no output schema present, the description carries the full burden and does so by enumerating the returned structure and the syntactic-only scope. It also covers the optional dbPath default and prerequisite, so nothing needed 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% and its parameter descriptions are already highly detailed (snapshotsBack indexing, typeName/methodName disclosure rules), so the schema does the heavy lifting. The description adds the cross-parameter constraint that an earlier save_session must exist, but otherwise largely restates what the schema 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?

States a specific verb (diff) and both operands (current session vs. a previously saved snapshot of the SAME solution), which cleanly separates it from save_session and other siblings. The scope of what is compared is unambiguous.

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

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

Gives the concrete prerequisite ('Requires a sessionId and at least one earlier save_session') and the default behavior (newest snapshot, or N-th via snapshotsBack), plus a redirect to find_symbol for spelling checks. It stops short of explicitly naming alternative tools or when-not-to-use cases, so it is clear but not fully 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 a safe, idempotent, non-destructive read, so the bar is lower; the description nonetheless adds rich behavior: empty include returns only source and names available axes, unknown include tokens are reported as dropped, '(none)' is an honest negative rather than 'not asked', multi-TFM solutions are deduplicated to the newest TFM, and the read is recall-safe from persisted facts. These are meaningful traits not expressible in 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?

Content is front-loaded with the core purpose and almost every clause carries non-redundant information (dedup, manifest honesty, budget fallback). However, it is an extremely long single paragraph with heavy nested parentheticals, which harms parseability despite the density.

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: it explains the manifest, the folded single-block partial-type rendering, the structural fallback under budget, and the honesty semantics of empty results. Given 100% schema coverage and annotations covering 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%, so a baseline of 3 applies, but the description adds real meaning beyond the schema: it defines the empty-vs-dropped-token semantics of 'include', the qualified Type.Member focus form for 'symbol', and the honest-negative behavior of the manifest. The budget semantics are already largely in the schema, so the added value is real but partly overlapping.

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 ('Explain') and resource ('a symbol') and defines the deliverable precisely as 'ONE dense AI-Builder-Markdown slice.' It explicitly distinguishes itself from siblings by naming the 4-6 calls it replaces (get_context + find_usages + find_implementations + find_tests_for) and from export_markdown. An agent can tell exactly what this does 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 gives explicit when-to-use ('the cold-read in a single call instead of 4-6'), an alternative preference ('prefer it over export_markdown for one symbol's world'), and a prerequisite workaround ('Pass a type or method simple name (use find_symbol to disambiguate)'). The selection logic against named siblings is fully 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 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 cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), yet the description adds substantial behavior beyond that: deterministic Roslyn evaluation, validity on recalled sessions, the 200-result cap, and the fact that the raw stored attribute list is returned with each hit.

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

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

Front-loaded with purpose then matching semantics, with zero filler sentences. It is dense and slightly long, but nearly every clause carries actionable detail, so it stays close to the top of the range.

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 that the raw stored attribute list travels with each hit, and it covers matching, kinds, member scanning, the method-axis nuance, determinism, and the result cap. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the attribute param's format-independent normalization (last segment, optional 'Attribute' suffix, case-insensitive, fully-qualified vs source-syntax storage) and the nuanced 'method' axis including .ctor/get_X/set_X. It leaves 'scope' semantics 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+resource ('Find symbols ... that carry a given ATTRIBUTE') and immediately differentiates from the sibling find_symbol by noting it is a 'cross-cutting query that find_symbol (name-only) cannot do'. 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?

Explicitly names the alternative (find_symbol) and the condition selecting this tool, plus concrete use cases ('[Obsolete]', '[ApiController]', '[Authorize]', test attributes). It also flags the value-add case where member scanning surfaces attributes a type/method-only scan misses.

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), so the bar is lower. The description still adds substantial behavior beyond that: a 200-type cap, exact-match semantics, default test exclusion, and detailed interpretation of empty results via subscriptionSitesChecked/Unresolved and the availableEvents/note/testMatchesFiltered fields.

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

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

Front-loaded with purpose and sibling differentiation before the dense return-shape guidance. The empty-result interpretation (the three site-count scenarios) is verbose, but with no output schema present, explaining the return envelope earns its place. Slightly long but well organized.

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 responsibly documents the return envelope (scope, event, counts, matches, note, availableEvents, testMatchesFiltered). Combined with the read-only annotations and full param coverage, an agent has everything needed to call 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: eventName is matched exactly, never as a substring, and omitting it lists every subscribing type; includeTests rationale is also explained. This goes beyond what the schema fields state.

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: finding TYPES that subscribe to a C# event via '+='. It explicitly distinguishes itself from the closest sibling, find_usages, by noting that tool lists subscribing/unsubscribing/raising METHODS while this works at type level and also sees external events like 'Button.Click'.

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?

Provides explicit use cases ('who listens to this event?', finding handler wiring), names the alternative (find_usages), and states exclusions ('+=' only, not '-='; a '+=' on a number, string or delegate field is skipped). When and when-not are both covered.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is low, and the description far exceeds it: it discloses max 200 items and types-first ordering, whole-value vs substring match modes, near-miss behavior, zero-match behavior of availableAxisValues, the fact that domain/responsibility are never inferred, that there is no 'Repository' role, and that test-project symbols are matched like production ones.

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 usage before the matching mechanics, return shape and edge cases, and nearly every sentence adds operational information an agent needs. Slightly dense across eight paragraphs rather than ruthlessly trimmed, which keeps it from a 5.

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

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

With no output schema present, the description carries the return-value burden and does so fully – criteria, note, minConfidence, matches (kind, name, declaringType, namespace, matched), matched source provenance, plus availableAxisValues and nearMisses when applicable. Nothing an agent needs to call and 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 the baseline is 3, but the description adds real meaning: filters combine with AND, layer/role match the whole value case-insensitively while domain/responsibility match as substrings, responsibility applies to types only, minConfidence rejects unknown values, and the echoed criteria encode the mode ('role=View' vs 'domain~order').

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 types and methods by their resolved semantics (layer, role, domain, responsibility) – which is a clear, distinctive capability. Concrete usage examples ('list the services of the Infrastructure layer', 'which types carry role X?') sharpen the intent. It does not name a sibling such as find_by_attribute or find_symbol to draw the boundary explicitly, so it stops short of a 5.

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

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

Gives explicit when-to-use examples and a hard precondition ('At least one filter is required'). It does not, however, state when to prefer an alternative tool or when this is the wrong choice, so the routing guidance to siblings is incomplete.

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 beyond the read-only/idempotent annotations: it discloses the 200-hit cap and sort order, the rejection semantics for out-of-vocabulary tokens and the effect+purity='pure' combination, the empty-result behavior via availableEffects, the unresolved-reference warning that can falsely report methods as pure, and that a hit does not distinguish direct from inherited effects.

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 in sentence one, and the dense prose largely earns its place by carrying behavioral detail no other field provides. It is on the long side and could be tightened (token meanings in a note could be shorter), but there is little outright waste.

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?

Despite there being no output schema, the description fully covers the return envelope (scope, effect, purity, methodsScanned, matches, note, availableEffects, testMatchesFiltered), the units included (methods, accessors, constructors, .ctor/.cctor), and caveats like the unresolved-reference purity warning. An agent has everything needed to call and interpret this.

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 3 baseline is met by the schema alone, but the description adds real meaning: effect tokens are a closed set where an invalid value is rejected rather than answered with zero, effect combined with purity='pure' is rejected, purity='pure' restricts the listing to methods only, and includeTests excludes test code by default with a stated rationale.

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

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

Opens with a specific verb and resource: 'Find code by its side-effect profile: what a method touches in the outside world.' It defines the closed token vocabulary and what a hit contains, so an agent can distinguish this from siblings like find_by_semantics, find_usages, or usage_report without opening another 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 when-to-use framing: "Use it for 'what hits the database or the network?' and to find pure methods," plus the fallback behavior when neither filter is supplied. It gives clear context but never names an alternative tool or an exclusion (e.g., when to prefer calls_external or find_binding_usages instead).

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 read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses the 200-item cap, that a listed candidate is only a suspect rather than proof, the exact exemptions (framework attributes, partial methods, Designer/generated files, static Main, PrintMembers, ShouldSerialize/Reset), which caller scenarios are not measured, and how to read an empty result against methodsIneligible. That is rich behavioral context rather than a restatement of the hints.

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 purpose and organizes the body by axis, exemptions, then return shape, so the structure is sound. It is nonetheless dense and uses long run-on sentences (the eligibility/exemption sentence in particular), which costs some readability even though most sentences carry 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 must carry the return contract, and it does: it names every returned field (scope, note, methodsScanned, deadMethods, typesScanned, deadTypes), the per-item shape, the counters and their zero-omission behavior. Combined with the exemption rules and the semantics of an empty result, an agent has enough 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 description coverage is 100%, so the schema already documents kinds, scope, sessionId and includeTests; baseline is 3. The description adds only marginal meaning beyond that — notably that an empty answer without a note implies an eligible population was judged, and that any other non-blank kinds value runs both axes — while not adding scope syntax or sessionId behavior beyond what the schema states.

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

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

States a specific verb and resource ('List dead-code suspects') and enumerates the two distinct axes it operates on (types with no incoming reference vs. private methods with empty caller lists). It also names the related sibling 'find_usages' as the source of the reverse type fan-in, letting an agent place it relative to siblings 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 clear selection guidance for the `kinds` axis, states the default (method), explains when to widen to 'all', and documents that test projects are excluded by default and what happens when other kinds values are passed. It does not, however, explicitly contrast the tool against plausible alternatives such as coverage_gaps or impact_of_change for a 'is this safe to delete' decision.

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 the safety profile (read-only, idempotent, non-destructive); the description goes well beyond them, disclosing the 100-item cap and name sort, the default exclusion of test implementers plus the testImplementationsFiltered counter ('so a short list is never silently short'), unresolved-closing marking, partial-inventory notes, generatedCodeNote, and hint behaviour. This is exactly the operational context 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?

Front-loaded with the core purpose and the sibling routing before the edge-case detail, and each sentence carries information. It is dense to the point of being long for a 3-parameter tool, but there is little outright waste.

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 contract itself: field list {name, isAbstract, kind, isTestProject, namespace, declaration, via}, count/totalFound/truncated, and the meaning of kind and via values. Nothing an agent needs to interpret or trust the result appears 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 schema already documents the arity suffix and concrete-type-argument forms, so the baseline is 3. The description nonetheless adds non-obvious semantics the schema omits: the name is case-sensitive, a namespace-qualified name matches nothing, and two interfaces sharing a simple name answer as one merged list.

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?

Starts with a specific verb+resource: 'List the types that implement an interface.' It also positions itself against named siblings — 'the interface counterpart to get_type_hierarchy (class inheritance) and find_overrides (methods)' — so an agent can discriminate without opening any schema.

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

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

Gives an explicit trigger ('Use it before changing an interface member, to find every type that has to follow') and routes elsewhere when the query is wrong ('when the name is not an interface (use get_type_hierarchy or find_overrides)'). Both when-to-use and when-not-to-use are covered.

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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial context beyond them: it reads current files on disk with bin/obj/.vs excluded, is never stale so no refresh_session is needed, works on recalled sessions, only handles string keys (not {x:Type ...}), ignores XML-commented markup, and caps lists at 200. The 'code' kind caveat (a matching literal is not proof of a lookup) is exactly the kind of nuance 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?

Front-loaded with the core purpose and the key-vs-audit branching, and nearly every sentence carries real information. It is a dense wall of text, though, and the C# string-literal caveat is restated in the fan-in paragraph after already being introduced in the reference-kind sentence, which costs some clarity.

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-value burden and does so: it describes definitions as x:Key file:line, references as file:line + kind ('static'/'dynamic'/'code'), same-file duplicate definitions, and the 200-item list cap. Combined with the stated blind spots, an agent has everything needed to call it and 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 description coverage is 100%, so the schema already documents key (case-sensitive exact match, omit for audit view), scope (solution vs view-path substring, references still counted solution-wide), and sessionId. The description reinforces the key/no-key split but adds no syntax or format detail beyond what the schema provides, 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+resource (find resource-key fan-in across XAML/AXAML markup and C# sources) and explicitly positions itself against the sibling capability ('the question the C# symbol graph cannot answer because resources are wired by string key, not by symbol'). An agent can distinguish it from find_usages and find_binding_usages 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 branching: with a key -> definition/reference lookup; without a key -> audit view of never-referenced keys and same-file collisions. It also states when the tool is insufficient (runtime-assembled keys, non-.cs source files, third-party dll templates) and what a zero-reference result actually means ('verify before deleting', not proof).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral context: what is deliberately not indexed (locals, parameters, labels, namespaces, generated obj/ declarations, .razor-only components) surfaced via 'generatedSourcesNote', the ranking algorithm (exact > case-insensitive > prefix > substring, then kind order), the 100-item cap and truncation semantics, and the 'nearest' suggestion on zero hits. These are genuinely beyond what the annotations provide, though the density makes some details hard to parse.

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 in sentence one, but the body is a single very dense paragraph that mixes ranking rules, kind ordering, non-indexed cases, truncation and typo handling. Anecdotes like the 'Type at position 1026 of 1102' history and the parenthetical asides inflate length without helping selection or invocation.

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 fully describes the return shape (items/count/totalFound/truncated, max 100), per-item fields (kind, name, declaring type, namespace, signature, project), and edge-case payloads ('generatedSourcesNote', 'nearest'). Nothing an agent needs to interpret or act on 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. The description nonetheless adds meaning beyond the schema: case-insensitive substring semantics, the operator metadata-name convention ('op_Equality', 'op_Implicit', 'op_' lists all), and what an enum member signature looks like. That is real added value over the two documented params.

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 ('Find types, methods, properties, fields, events, enum members and operators whose name contains the query') and enumerates exactly what the search covers. It is clearly distinguishable from siblings like find_usages, call_graph and get_context, which it explicitly positions itself as a precursor to.

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 rule ('locate a symbol before calling find_usages / call_graph / get_context') and explains the handoff mechanism (every kind listed is one those tools resolve; operators by metadata name). It also tells the agent what to do when results are truncated or empty, which is actionable 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), but the description adds substantial context beyond them: the two-hop evidence limit, the truncation cap of 50, the meaning of an empty answer, and the specific cases where the returned numbers mislead (undeclared names, event/enum members, nested types, constructor queries). This is unusually rich disclosure for a read-only 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?

Front-loaded with the core purpose and the sibling distinction, and each sentence carries information an agent needs. The middle paragraph enumerating nine matchReason tiers is dense, but with no output schema this return-value semantics has to live somewhere. Slightly heavy, though nearly every clause earns its place.

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 full burden of explaining the return shape, and it does: the item fields, count/totalFound/truncated, invokesTotal/dispatchTotal, the optional note, and the tier taxonomy in sort order. Combined with the case-sensitivity rule for the input, 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 baseline is 3, but the description adds real meaning beyond the schema: 'symbol is case-sensitive' and the three accepted forms including 'Type.Type' for a constructor, which the schema does not spell out. The added constraint materially affects how an agent passes the argument.

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 test cases that likely cover a symbol') and immediately scopes what counts as evidence ('static evidence, not a coverage run'). It explicitly distinguishes itself from the sibling coverage_gaps ('asks the reverse for a scope'), 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 explicit when-to-use guidance in both directions of a workflow: 'before changing a symbol, to see what pins it, and after, to pick tests.' It also names the alternative tool and the condition that selects it, and states what the tool is NOT (a coverage run).

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 covering the safety profile (readOnly/idempotent/non-destructive/closed-world), the description still adds substantial behavioral context the annotations cannot: the conservative 'skip carries the accuracy claim' recall-vs-precision contract, the single measured false-report class with its fixture-pinning, the caveat that a hit is evidence to verify not proof, and the live-analysis requirement ('call refresh_session after edits') plus the recalled-snapshot failure mode.

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 routing before drilling into coverage mechanics, returns, and caveats, and each paragraph has a distinct role. It is nonetheless very long and dense for a one-parameter tool, with the skip/accuracy rationale restated, so it stops short of maximal conciseness.

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 fully specifies the return shape (count, unresolvedBindings with view/viewModel/member/line, markupFilesScanned, bindingSitesInMarkup, sitesJudged, sitesSkipped, sitesSkippedBy, judgementNote) and how to interpret a zero. Nothing an agent needs to call or correctly read 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?

One parameter with 100% schema coverage, so the schema fully documents sessionId (session_id from analyze_solution, or an absolute .sln/.slnx/.slnf path). The description adds no additional syntax or format meaning beyond that, 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 and resource ('List silently broken XAML bindings: a {Binding X} whose root member does NOT exist on its confidently resolved DataContext view-model') and pins the exact defect class ('neither the compiler nor render-smoke tests catch'). It distinguishes itself from find_binding_usages and find_resource_usages by name, so an agent can route without opening a schema.

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

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

Gives an explicit trigger ('Use it after renaming or removing view-model members'), states its scope limit ('judges the ROOT member of a binding path only'), and names the alternatives for the adjacent task ('To see where a member or a resource key is bound use find_binding_usages / find_resource_usages'). When-to-use, when-not, 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: the capped envelope (at most 100, truncated flag), the meaning of empty results, namesake/collision semantics, selfReferences and textuallyInvisibleUsers, and not_found caveats. This is unusually rich disclosure for a read 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?

Purpose and routing are correctly front-loaded, and most clauses carry genuine behavioral content, but the middle is a dense run-on of semicolon-chained enumerations (resolvedKind branches, envelope fields, optional members) that is hard to scan. It is informative but over-sized.

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 return semantics — and it does fully: top-level fields, the usedBy envelope, per-item shape {name, file, line}, multi-file declarations, fullName/project disambiguation, and all optional qualifier members. 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 schema already documents both parameters, but the description adds real meaning: how symbol resolves differently by resolvedKind (type/method/property/field/event/enum_member/operator/constructor) and the case-sensitivity constraint. It goes beyond the schema's restatement of the Type.Member/Type.Type forms.

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 who uses a symbol: its direct fan-in.' It immediately distinguishes itself from siblings by naming impact_of_change (closure/risk) and calls_external (external members), 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?

States explicit when-to-use ('before changing or deleting a symbol'), when-not (instead of grepping a C# name), and the alternatives for the adjacent cases. It even covers edge conditions — empty usedBy is not proof of dead code, 'not_found' is not 'undeclared' — so the agent knows how to interpret negative results.

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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description builds on that with rich behavior no structured field captures: snapshot-based rather than disk-based results, verdict:'stale' semantics, the #pragma exclusion, the 200-item cap with full counts, incompleteProjects magnitude caveat, cascadeFromIncomplete propagation, generatedCodeGaps, and designTimeBuildFailures. This is well beyond the annotation bar.

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

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

Front-loaded with the primary purpose, then sequencing, then the verdict/return contract, then disclosures. Dense but the disclosures block is a long list of caveats that, while valuable, makes the description heavy. Structure is logical and every clause earns its place, but the volume is near the upper limit for one 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?

For a tool with 3 params, no output schema, and complex return semantics, the description supplies the return shape (verdict, projectsScanned, counts, up-to-200 diagnostics), the meaning of stale/inconclusive verdicts, and the caveats behind the counts. An agent has everything needed to call it and interpret the result 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 adds real meaning for scope beyond the schema: it filters the answer not the work, every project compiles either way, and the token-saving intent is stated. severityFloor is left entirely to the schema, which is fine given full coverage, but the scope nuance is a genuine addition.

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+resource: compiler errors and warnings, compiled in memory without a build. It explicitly distinguishes itself from sibling list_insights, which reports design findings instead. An agent can tell what this tool does and how it differs from adjacent 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?

Explicit when-to-use sequencing: 'after editing .cs files: refresh_session, THEN this'. Names the stale-answer failure mode, tells the agent to call refresh_session(force:true) after restore/build, and warns that an unforced refresh may answer 'unchanged'. Also states the tool needs a live session and rejects a recalled one. This is strong routing and prerequisite 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 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 no destruction, so safety is covered; the description goes far beyond that with return fields (directCount, transitiveCount, productionImpactCount, directImpact, risk), the risk thresholds tied to productionImpactCount, per-kind closure semantics, implementers/riskBasis behavior, and the note/not_found/collision caveats that flag misleading counts.

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?

Long and dense, but front-loaded (purpose, then call-order guidance, then return/behavior details) and nearly every clause carries distinct information. The remaining cost is readability: the risk-threshold and note/collision material is packed tightly enough that it slows scanning.

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

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

There is no output schema, so the description must carry return-value meaning, and it does: exact field names, risk mapping, per-kind closure definitions, and edge-case blocks (saturation, implementers, namesakes, note, collision). Little 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 the baseline is 3, but the description meaningfully extends the symbol parameter: case-sensitivity, simple-name vs bare-member vs 'Type.Member' resolution, and that constructors are not resolved. That is genuine semantic value 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 and resource ('Estimate the blast radius of changing a symbol: its direct users plus their dependents, with a risk level') and immediately scopes it as the pre-edit step. It also distinguishes itself from find_usages by adopting its resolution rules while carving out constructors, so an agent can tell what it does and does not cover.

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

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

Gives an explicit use trigger ('Call it first, before any edit to a symbol other code names (a rename, signature, default value)') with the reason (compile checks names, not consumer assumptions). It names the alternative for an excluded case: a constructor 'is not resolved here: use find_usages'.

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, but the description adds context beyond them: it writes no config or DB row, marks nothing initialized, walks a warm session workspace without re-analysis, requires a live session, and rejects a recalled one with an error. These are real operational traits not 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-loads purpose and the step-1-of-2 routing, then handles returns. It is dense and long, but with no output schema the return-format sentences earn their place; a few clauses (e.g., the envelope field enumeration) run long for the value added.

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 documents the return JSON (solutionPath, declaredNamespaces, referencedNamespaces, testProjects, detectedTestAttributes, proposalFormat), the capping of the three envelope lists, and the asymmetry between solutions' own vs external namespaces. 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?

Only one parameter (sessionId) with 100% schema description coverage; the schema already documents that it accepts a session_id or an absolute .sln/.slnx/.slnf path. The description adds no further meaning about the parameter itself, 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 and resource: collecting raw material for guided setup of a solution's Layer Profile, Exclude-Namespaces and Test Profile. It explicitly positions itself as 'step 1 of 2' and names apply_solution_config as the writing step, distinguishing it from 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?

Gives precise trigger conditions: use when solution_config_status or the configInit hint of analyze_solution reports an axis as not initialized, or when check_solution_config_drift reports one as stale. Names two alternatives (apply_solution_config for writing, solution_config_status for viewing) with the exact conditions selecting each.

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 cover read-only/idempotent/no-open-world, but the description goes well beyond them: it defines 'created' vs 'injected', states no container is consulted, notes test-project sites are included not filtered, explains the two-zero 'note' cases and 'nearest'. It does not spell out pagination/ordering guarantees beyond 'created first, max 200', so a 4 rather than 5.

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

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

Front-loaded with the core purpose and the sibling contrast, then organized into labeled sections for the two kinds of site and the return shape. It is dense and long, but nearly every sentence carries distinct semantic payload; only marginal trimming 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, yet the description enumerates the returned fields (typeName, note, the four counts, sites, nearest) and explains how to read the counts and the zero-site 'note'. 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 schema carries the parameters; the description still adds real meaning by defining scope as a prefix on the SITE's namespace and by explaining typeName's simple-name matching, namesake unioning, and external-type validity.

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 ('find where a type is constructed and injected') and immediately distinguishes itself from siblings: find_usages answers 'every reference' and resolve_injection answers 'what is registered'. An agent can route between all three without opening a schema.

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

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

Gives explicit when-to-use ('before changing a constructor', 'to see whether anything but a test builds a type') and names the two alternative tools with the exact question each answers instead. 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: it discloses that results are triage-filtered on BOTH axes (intentional suppressions and user dismissals), that fully-filtered insights disappear, how the 'suppressed' count combines both axes, and that 'title' is pre-filter producer text while detailsCount+suppressed is the real split. It also flags remediationCostMinutes as a coarse estimate. This is exactly the behavioral context 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 is front-loaded, which is good, but the description is dense and winding — the triage-filtering and profile-precedence passages are convoluted and could be tightened. Given the tool's complexity most content earns its place, but the structure is heavier 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?

With no output schema, the description carries the return-shape burden and does reasonably well: it explains per-producer aggregation with a Details list and the meaning of suppressed, detailsCount, title, and remediationCostMinutes. A bit more on the overall shape would make it fully complete, but it is close.

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 both parameters are already documented in the schema, including dbPath's profile-resolution behavior. The description largely restates that precedence nuance rather than adding new syntax or format detail, 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?

States a specific verb and resource with concrete scope: 'List code-quality / async / design-smell insights for a session', reinforced by named example categories (long methods, fat interfaces, unused types). It clearly reads as the list-side counterpart to get_insight, but it never explicitly differentiates itself from that sibling, so an agent still has to infer list-vs-single.

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 real conditional guidance for the dbPath parameter (pass to use the DB's QualityProfile, omit for the default DB-free profile) and explains precedence against analyze_solution(layerProfile). However, it offers no explicit when-to-use-this-vs-alternatives routing against siblings like get_insight or solution_metrics; usage is implied rather than directed.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), but the description goes far beyond: it discloses the cheap W0 hash pre-check, the source-file-only blind spot (misses restore/build), the automatic single retry, and the reuse of a warm workspace. These are non-obvious behavioral traits the annotations cannot convey.

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

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

Front-loaded with the core action and the stale-graph warning, then caching, then return shape - a logical order with no filler sentences. It is dense and long, packing several distinct concerns into one paragraph, which costs a little scannability but 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, yet the description fully documents the return object ({changed, reason, session, mode}) and the meaning of 'mode' and its absence. Combined with annotations, an agent has everything needed to call it correctly and interpret 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%, so the baseline is 3, but the description adds real meaning to 'force' (deterministic demand for re-analysis after a restore/build, full MSBuild cost) and reinforces sessionId semantics. It exceeds the schema rather than merely restating 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+resource ('Re-analyze the session's solution after YOUR code edits') with the triggering condition (changed .cs files). It explicitly distinguishes itself from the read-only analysis siblings that would otherwise answer from a stale graph, so an agent can pick it without opening any schema.

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

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

Gives explicit when (after editing .cs files), when-not (a save without an edit, an unchanged file-set hash), and the exact alternatives that go stale (find_usages / impact_of_change / list_insights / get_context). It also names the escalation path 'force' for restore/build scenarios, leaving nothing to inference.

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

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

Annotations only declare read-only/idempotent/non-destructive; the description goes far beyond, enumerating exactly which registration forms are read (Add{Singleton,Scoped,Transient}, TryAdd*, AddHostedService, foreach static table) and which are not (Scrutor, other containers, AddHttpClient-style). It also discloses the 'inferred, not read' provenance, the 'needs a live session' requirement, and the 'never not registered' caveat for empty results.

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

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

Front-loaded correctly (purpose first, exclusions second), and given there is no output schema nearly every clause earns its place. It is, however, extremely dense—the return-shape enumeration is a run-on separated by semicolons that is hard to parse on a first read.

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 documents the JSON keys (registrations, ambiguous, effectiveRegistration, consumedAsCollection, constructorConsumerCount, optionalDependencies), the empty-list semantics, session requirements, and test filtering. An agent has what it needs 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 semantics the schema does not: 'interface is the SERVICE type (an interface, or a class registered as itself)' and the typeArgumentFilter distinction for closed vs open generics. Some of the site/includeTests text duplicates the schema, keeping it 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?

Opens with a specific verb and resource: 'Resolve a Microsoft DI registration: what is registered for a service, with lifetime and site.' It then explicitly names the sibling tools it is NOT (find_usages, find_implementations, instantiation_sites), 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?

States when to use it versus three named alternatives, defines the empty-result case ('not_found' + 'nearest' vs a note naming unread forms), and specifies the includeTests=true condition with testRegistrationsFiltered. Both when-to-use and when-not-to-use are covered.

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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description goes well beyond them: it scopes the write to the aicb DB rather than source/config, enumerates the rows created, states a missing DB file is created, and stresses nothing is overwritten with name as a label not a key. It also discloses a subtle downstream behavior (lineNumbersAvailable false on recalled sessions).

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

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

Front-loaded with the action, then usage, then return shape, then side effects, then parameters — a logical progression with no filler. It is on the long side for a three-parameter tool, but each paragraph carries distinct information rather than restating the schema.

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

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

With no output schema, the description carries the return contract itself (snapshotId, sessionId, solutionId, name, lineNumbersAvailable, totalSnapshots) and covers the DB-write side effects and the dbPath failure mode. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: sessionId may be a live or recalled session id OR an absolute .sln path, and omitting dbPath uses the server's standard config DB with the explicit failure mode 'dbPath is required' when none was resolved. That failure-mode detail is not derivable from 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+destination: 'Persist the current session's analyzed model as a named Manual snapshot in an aicb DB.' It explicitly frames the artifact against the sibling that consumes it (compare_with_previous), so an agent can place it without opening the schema.

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

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

Gives an explicit trigger ('BEFORE a bulk mechanical change'), the follow-up action (call compare_with_previous afterwards), and an explicit non-trigger ('An ordinary edit needs no snapshot: git diff and the tests cover it'). This is the strongest form of when/when-not guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavioral context beyond that: it needs no session, is a reachability smoke-check, returns plain text not JSON, documents the exact line-1 format, and explains exactly when each drift line appears or stays silent. This is rich operational detail that 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 the purpose and usage in the first sentence, but the body is dense and grows into a long enumeration of drift lines and format rules. Each sentence carries content, yet the whole is closer to a reference block than a tightly edited summary, which hurts scanability.

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 zero-parameter, no-output-schema tool and an idempotent read-only annotation set, the description covers everything needed: why to call it, what it returns, every drift line's meaning and firing condition, and the exact text format to parse. Nothing material is missing for an agent to invoke 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?

The tool takes zero parameters, so the baseline per rubric is 4. The description does not invent any parameter discussion, which is correct, and its complete output-format documentation compensates fully for the absent parameters.

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

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

Opens with a specific verb+resource ("Report this SERVER's own identity and health") and enumerates exactly what is returned: name, version, build commit, config DB schema version, drift warnings. It explicitly distinguishes itself from siblings (solution_config_status, check_solution_config_drift, list_skills, usage_report) by naming what it does NOT cover.

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 after connecting and after an update or restart," plus the specific question it answers that the version number cannot. Names sibling alternatives (solution_config_status, check_solution_config_drift, list_skills, usage_report) and the boundary of what each covers, so routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantial non-obvious semantics: 'initialized' is an explicit marker stamped by apply_solution_config and NOT inferred from an active id set manually. It also explains source provenance ('db', 'sidecar', 'built-in', 'none'), including the important edge case that a repo with a valid .aicb.json sidecar but no DB row still reads initialized=true / source:sidecar.

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 is front-loaded, but the body is a single dense paragraph with deeply nested parentheticals and semicolon-chained clauses that make it hard to scan. Much of the content earns its place (no output schema exists, so return-value semantics matter), but the structure could be broken up without losing 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 fully: it defines the three slots, their initialized flags, the active configuration per slot, the effective test-detection profile, and the four possible source values. It also covers the sidecar edge case and prescribes the follow-up action, so an agent has everything needed to call and act on 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 description coverage is 100%, so the schema already documents sessionId (including that it accepts a .sln/.slnx/.slnf path) and dbPath. The description largely restates the dbPath default behavior ('omit it to use the server's default config DB'), adding little beyond the structured field. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb (check) and resource (solution configuration status), enumerating exactly which three slots are inspected (Layer Profile, Exclude-Namespaces, Test Profile) and what 'active' means for each. It is clearly distinguishable from siblings apply_solution_config and init_solution_config, which it explicitly references as the write-side counterparts.

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 an explicit trigger ('Use this on solution start') plus a concrete conditional workflow: if a slot is not initialized, offer init_solution_config + apply_solution_config. That names both the when and the alternative tools, leaving nothing to inference.

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

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

Annotations cover only the read-only/idempotent safety profile; the description adds substantial behavior: production-only scope with test counts reported separately, degradedProducers signalling incomplete severities/debt, debtMinutes being a coarse per-finding estimate, severities counting insights not findings, strict vs inclusive threshold semantics, and non-triage-filtered counting of suppressed findings.

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

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

Front-loaded with purpose and routing, and nearly every sentence carries a distinct behavioral fact. It is dense to the point of strain in the closing profiles paragraph, where nested parentheticals ('the one dbPath (or, omitted, the session's analysis DB) configures') slow parsing, but little is genuinely expendable.

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 returned fields (metrics, scope, severities, debt, gate, degradedProducers) and their caveats, plus scope/profile behavior and the DB-upgrade side effect. An agent has everything needed to call it and interpret 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%, so the baseline is 3, but the description still adds meaning: failOn must use tokens from knownGateMetrics and is rejected with the known tokens on error, and dbPath controls which QualityProfile supplies the threshold. sessionId's .sln path acceptance is only restated from 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+resource: the 'solution-wide quality rollup in one call' that the CLI '--fail-on' gate evaluates. It explicitly distinguishes itself from symbol_metrics (single methods) and list_insights (findings behind severity counts), so an agent can pick it without opening the schema.

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

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

Gives concrete when-to-use conditions ('a before/after number, or to try a gate expression') and names the two nearest alternatives with the axis that separates them. It also warns that this gate is advisory while the blocking one is the CLI's, which prevents misuse.

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