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

With no annotations provided, the description carries the full behavioral burden and handles it thoroughly. It discloses edge traversal rules, exclusions of structure/external nodes, default behavior matching the CLI, output format differences, and the semantics of unresolved-call 'coverage' as an upper bound with potential false positives. This is highly transparent about what the operation actually does.

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

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

The description is dense but every sentence earns its place. It front-loads the core definition, then moves to exclusions and sibling routing, then parameter-specific behavior and output semantics. There is no filler or repetition of schema 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?

For a tool with six parameters, multiple output modes, and nuanced filtering behavior, the description is remarkably complete. It covers scope, edge types, output payload shape, unresolved-call semantics, CLI equivalence, and alternatives. Even though an output schema exists, the description's own explanation of return values and coverage is a helpful addition rather than a redundancy.

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

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

Although schema coverage is 100%, the description meaningfully enriches each parameter: fqn ambiguity and candidate resolution, db_path resolution being relative to the server's working directory, output_format being case-insensitive and rejecting other values, and include_structure/include_external clarifying containment and runtime-typed call targets. This goes well beyond the schema's baseline.

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 line states a specific verb and resource, 'Upstream subgraph of one FQN,' and immediately clarifies the exact graph relationship and depth hop limit. It explicitly distinguishes itself from sibling tools by naming cgis_trace_flow, cgis_get_structure, and cgis_context, so an agent can select this tool versus alternatives without inspecting their 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?

The description clearly states when this tool is appropriate: it answers 'what breaks if I change X?' and gives explicit alternatives for related needs: cgis_trace_flow for dependencies, cgis_get_structure for members, cgis_context for editing one symbol. It also states which edges are excluded by default and how to opt into them, leaving no ambiguity about when to use this tool.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses that reachability follows CALLS and DEPENDS_ON edges, that DI-wired guards count, that output is {target, covered, gaps}, and that no-match selections raise a ❌ error rather than an empty passing result. It also warns of a known edge case (#467). This is more transparency than typical.

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

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

The description is long but tightly packed: each paragraph covers one concern (headline use, selection, output/edge case) and the main verb appears in the first line. No filler or repetition of schema defaults. The front-loaded headline sentence makes the tool's purpose instantly 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?

Given the tool's complexity, the description covers purpose, use cases, source selection, edge behavior, and return shape; the output schema and parameter descriptions fill in return and depth details. The only mild omission is explicit sibling guidance, but the rich use-case section compensates. The definition gives an agent enough to call 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 covers all five parameters, so the baseline is 3, and the description adds real meaning: it explains the at-least-one-of from_type/from_prefix selection constraint, how prefixes are matched on whole dot-segments, and that target points at the checkpoint. It does not add much for depth or db_path, but those are already well documented in the schema.

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

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

The description defines a specific verb and resource: it audits reachability to a checkpoint and lists sources that never arrive. It names a concrete headline use (IDOR/authz coverage) and distinguishes its traversal semantics (CALLS plus Depends()) from a plain graph query. This is enough to separate it from siblings like cgis_trace_flow or cgis_find_orphans.

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

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

It explicitly frames when to use the tool: for IDOR/authz coverage audits, and it generalizes to validators, event tracking, and service-layer-boundary rules. It also gives selection rules (from_type and/or from_prefix) but does not name sibling tools to avoid or state a when-not-to-use condition. That is clear context without exclusions.

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 no annotations, the description carries the full burden and does so thoroughly: it discloses that only calls are followed, depth defaults to one hop, source is included only when found, source_root behavior including the #228 edge case, and graceful degradation to 'unavailable'. This is rich behavioral disclosure beyond what any schema field states.

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 immediately states the core deliverable and scope. Subsequent paragraphs each add distinct value: usage guidance, alternative routing, return format rationale, prerequisites, and parameter edge cases. Nothing is wasted, and the most decision-relevant information is front-loaded.

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

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

For a 4-parameter tool with no annotations, the description covers prerequisites, alternatives, parameter edge cases, output format, and failure behavior. Even with an output schema present, the description's explanation of the XML-tagged prompt and token efficiency adds value an agent cannot infer from the schema alone.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaningful parameter nuance: source_root is safe to pass even when stored paths already start with that segment, emptiness means the server's working directory, and depth one hop means direct callers/callees. This goes beyond the schema's own parameter descriptions.

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

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

States a specific verb and resource: returns a prompt-ready brief on one FQN covering source, class, direct callers, and callees. It also distinguishes itself from siblings by naming cgis_trace_flow and cgis_analyze_impact as multi-hop alternatives, so an agent can tell the tools apart.

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 ('before editing a symbol, instead of reading its files'), when not to (for multi-hop subgraphs use cgis_trace_flow or cgis_analyze_impact), and what prerequisite to check ('Use cgis_ingest first if the database does not exist'). This leaves no ambiguity about placement among siblings.

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 no annotations provided, the description fully discloses behavior. It details the return JSON structure (any_critical, per-domain reports with fit blocks, quotient layer, coverage), explains the nuanced behavior of max_drift (now a default tolerance only for domains without their own), and clarifies max_residual's independence from drift tolerance. This goes beyond a simple report description and covers edge cases and parameter 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?

The description is moderately long but well-structured with paragraphs and code formatting. It front-loads the purpose and return format, then addresses parameter nuances. Each sentence carries informational weight, and the use of backticks and references (#170, #177) adds precision without excessive verbosity. It could be slightly tighter, but it is not padded.

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

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

Given the tool's complexity, the description is thorough. It covers the return format, when to call it (after cgis_ingest), parameter behaviors, and even notes the change in max_drift semantics. The presence of an output schema reduces the need to detail return values, and the description fills the remaining gaps. No essential information for correct invocation is missing.

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

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

Schema coverage is 100%, so all parameters are already documented. The description adds value by clarifying semantics beyond the schema: max_drift's role as a default only for domains lacking their own tolerance, profile's purpose for filtering by language, and max_residual's meaning for fit.band classification. This extra context elevates the description above the baseline 3.

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 clearly states the tool's function: 'Report per-domain architectural drift against declared ideal patterns.' It uses a specific verb ('report'), a clear resource ('per-domain architectural drift'), and the context ('against declared ideal patterns'). This distinguishes it from sibling tools like cgis_validate or cgis_metrics, which serve different analytical purposes.

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

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

The description gives explicit usage context: 'Call after cgis_ingest to learn whether your edits pushed a domain past its drift tolerance.' It also provides conditional usage for the 'profile' parameter ('Use when your patterns.yaml mixes languages...'). While it doesn't explicitly mention when not to use the tool or name alternatives, the clear trigger condition and parameter-specific guidance make the usage intent strong.

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 no annotations provided, the description carries the full burden — and it excels. It discloses the return shape {orphans, considered, test_sources, generated_excluded}, the error bias (errs toward reporting a live class rather than hiding a dead one), the invisible cases (decorator-only names, star imports), the test_sources: 0 meaning re-ingest, the generated_excluded counting semantics, and the machine-generated hidden-by-default behavior with a measured example. This is exceptionally rich behavioral disclosure.

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

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

The description is long and dense. Most content earns its place — the caveats about decorators, star imports, and re-ingest are genuinely important. But it carries some bloat: the commit hash b7d02fe6, issue numbers (#432, #429), and the '43 of 1 789 classes' anecdote add authenticity but length without changing agent behavior. The first sentence is awkward. It is structured in digestible paragraphs and reasonably front-loaded, but not lean.

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

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

For a complex dead-code analysis tool, this is complete. Even though an output schema exists, the description goes beyond it by explaining the failure modes (test_sources: 0 meaning stale graph, generated_excluded: 0 with generated code meaning missing backfill), the false-positive bias, and the filtering semantics. An agent has everything needed to invoke it correctly and interpret results — nothing critical 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 schema's own parameter descriptions are already strong. The tool description adds meaningful nuance on top: prefix's dot-boundary cutting, include_tests converting the report to 'unreachable from anywhere', and include_generated framing generated classes as noise rather than findings. This goes beyond the schema baseline of 3, though the schema already did heavy lifting, so the increment is moderate.

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 clearly identifies the tool's job: finding dead-code candidates (orphan classes). The second paragraph clarifies the purpose precisely — classes kept importable by re-exports but with no real callers. However, the opening sentence 'Classes nothing in production builds, extends or names' is awkwardly phrased and reads like a fragment; the intent is recoverable but the first line hurts clarity. The description does distinguish this from siblings by framing it as a dead-code sweep rather than a reachability/impact query.

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

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

The description explains the tool's philosophy deeply — tests are not users, re-exports are not uses, what counts is CALLS/EXTENDS/REFERENCES — which implicitly tells an agent when this tool applies. It also explains how flags change the semantics (include_tests becomes 'unreachable from anywhere'). However, it never explicitly names sibling alternatives or states when NOT to use this tool in favor of, say, cgis_audit_reachability or cgis_analyze_impact. The usage context is strong but the exclusion/alternative routing is absent.

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 no annotations provided, the description carries the full burden. It discloses the ranking order (exact > prefix > substring), the JSON return shape, and that kind/fqn_prefix filter results. It does not explicitly state the operation is read-only, but as a lookup tool this is implied. It adds meaningful behavioral context beyond the schema.

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

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

Three sentences with no filler. The purpose is front-loaded, usage guidance follows immediately, and the return format and key filters are mentioned compactly. Every sentence 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?

For a 5-parameter tool with an output schema and no annotations, the description covers the core purpose, when to use it, return format, and two of the filtering parameters. It omits explicit mention of 'limit' and 'db_path', but those are fully described in the schema. Error behavior (e.g., unknown kind) is covered in the schema, not the description, which is acceptable.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds marginal value by relating 'kind' and 'fqn_prefix' to their filtering effects, but it does not elaborate on 'limit' or 'db_path'. This is baseline 3 with slight extra context.

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 precise verb+resource: 'Resolve a partial symbol name to candidate FQNs (substring match, ranked).' It explicitly names the sibling tools it precedes (cgis_trace_flow, cgis_analyze_impact, cgis_get_structure), making differentiation clear without reading schemas.

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

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

It gives an explicit condition for use: 'Call this BEFORE cgis_trace_flow / cgis_analyze_impact / cgis_get_structure when you know a short name but not its full FQN.' It even states the alternative it removes ('read-the-file-first guesswork'), leaving no ambiguity about when to invoke this tool.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it delivers: it explains that the tool is observe-only, enforces nothing, is read by no gate, and that the verdict is a lossy summary of a non-linear curve. This goes well beyond a basic 'returns JSON' statement and tells the agent what to trust and what to interpret carefully.

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?

Every sentence in the description earns its place: purpose, method, output shape, verdict semantics, interpretation warning, observability, and prerequisite. The first line is front-loaded as a crisp summary, and the rest expands only where the agent genuinely needs more context.

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

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

The description fully covers what the tool does, how the analysis works, what the output contains, how to interpret the verdict, and when to call it. Given the tool's complexity, this is a complete operational explanation; the input schema is simple and fully documented, and the return shape is itemized in detail.

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

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

Schema description coverage is 100%, so the input schema fully documents db_path, including the relative-path resolution behavior. The description adds no extra parameter details and does not need to; the schema already carries the load, 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 opens with a precise verb-resource pair: 'Report the motif census across the repository's structural tiers.' This uniquely identifies the tool's function and clearly separates it from siblings like cgis_metrics or cgis_get_structure by naming a specific analytic artifact (motif census) and a specific method (coarsening along structural tiers).

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

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

The description gives clear context for invocation: 'Call after cgis_ingest' and 'Observe-only: this tool enforces nothing and no gate reads it.' It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the sequencing and observational caveat provide solid practical 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?

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly: package nodes are synthesized with virtual file paths, the output shape depends on output_format, and it matches the CLI structure command. It discloses notable edge cases such as packages not being graph nodes.

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

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

The description is front-loaded with a crisp one-line definition, followed by scope constraints, alternatives, and output details. Every sentence earns its place; even the package-node nuance and sibling references are necessary for correct 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?

For a tool with no annotations, sample schema descriptions, and an output schema indicated, the description covers the important behaviors, alternatives, and parameter-specific output semantics. Nothing needed for correct selection or invocation is missing.

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

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

Schema coverage is 100%, so the schema already describes all four parameters well. The description adds extra meaning beyond the schema for output_format by specifying the JSON payload as 'joinable {root, nodes, edges}' and clarifying that the mermaid diagram is rooted at the given FQN.

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+resource: it returns members of a module/class or modules held by a package prefix, and explicitly states it follows containment only. It distinguishes itself from cgis_trace_flow and cgis_analyze_impact by name, so an agent can select the correct tool without inspecting 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?

It explicitly states when to use alternatives: use cgis_trace_flow for dependencies or cgis_analyze_impact for dependents when code connectivity is the question. It also clarifies containment-only semantics (no calls/imports), which defines the boundary of this tool's scope.

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 no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses that ingest is incremental by default, that the whole graph is rebuilt when resolution changes occur, that full_rebuild=True forces a full rescan, that the graph is portable due to FQN normalisation, and that cgis will not create parent directories.

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

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

The description is front-loaded with the core purpose and then adds necessary caveats and behavioral details in a logical order. Every sentence contributes either to usage, path constraints, or incremental rebuild semantics; nothing is redundant.

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

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

Given the output schema exists and the parameter count is only three, the description is complete. It covers the operation, default behavior, rebuild behavior, path constraints, and even what the summary reports, leaving no critical gap for invoking 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 baseline is 3, but the description adds substantial meaning beyond the schema: db_path constraints are elaborated, the incremental-vs-full-rebuild behavior is explained, and the relative-path resolution for both db_path and project_path is clarified. This exceeds what the schema alone 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?

The description states a concrete action chain — scan a directory, extract symbols, resolve links, and build the graph DB — and explicitly says it initializes or refreshes a project's code knowledge graph. This clearly separates it from the sibling analysis tools like cgis_trace_flow or cgis_analyze_impact.

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

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

The description gives a clear usage context: 'Use this to initialise or refresh the code knowledge graph for a project.' It does not explicitly enumerate when not to use it or name alternative tools, but the context is specific enough that an agent can identify the appropriate situation.

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?

No annotations are provided, so the description carries the full burden. It explicitly states the operation is read-only, that 'No files are written', and that the caller decides where to persist the output. This fully discloses the behavioral impact, leaving no hidden side 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?

The description is compact and front-loaded: purpose first, then output and persistence behavior, then margin semantics. Every sentence earns its place, with no redundant filler beyond the deliberate repetition of the read-only/no-write guarantee for emphasis.

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 an output schema exists and all parameters have schema descriptions, the description still covers the essential workflow context: what the tool returns, how to use it downstream, and the absence of side effects. Nothing an agent needs to correctly call and interpret this 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 description coverage is 100%, so the baseline is 3. The description adds meaningful interpretation beyond the schema by explaining that tolerances are 'measured scores plus margin' and framing them as a ratcheting baseline rather than a verdict. This gives strategic context for margin, though it does not add additional semantics for depth, db_path, or min_nodes.

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

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

The first sentence states a specific action ('propose a starter patterns.yaml'), the resource ('from the measured graph'), and the read-only nature. It clearly differentiates itself from sibling tools like cgis_drift by framing the output as a starting artifact to be consumed by cgis_drift.

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

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

The description gives an explicit workflow: generate the YAML, save it, review the labels, then run cgis_drift with it. It also explains the semantic role of the output ('a baseline to ratchet down, not a verdict'), which helps the agent decide when this tool is appropriate. It lacks explicit when-not-to-use guidance or named alternatives, so it stops 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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the optional duckdb dependency, how unavailable dependencies are reported, how exclude removes nodes from PageRank propagation, how scope differs in propagation semantics, and that coupling in-degree still counts callers outside the scope. This goes far beyond the schema and annotative defaults.

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

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

The description is front-loaded with the core purpose and result shape, then dives into parameter semantics and behavioral nuances. It is longer than a minimal definition, but most sentences earn their place because they clarify subtle ranking behavior that materially affects invocation and interpretation. A slightly tighter ending would make it even cleaner.

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

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

Given the tool's algorithmic complexity and the absence of annotations, the description is remarkably complete: it covers return shape, dependency risk, error behavior, parameter semantics, composition rules, and the graph-propagation model. An agent has enough information to select, invoke, and interpret the results correctly without additional documentation.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it gives concrete examples for exclude (tests.* and domains.*.tests.*), explains dot-boundary anchoring for scope, describes how the two parameters compose, and clarifies their differing effect on PageRank and coupling measurements. This is exactly the kind of semantic enrichment the schema alone cannot provide.

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 and resource: computes whole-graph architectural metrics (coupling bottlenecks, God classes, PageRank). It explicitly distinguishes itself from node-local trace/impact/context tools, so an agent can identify what this tool is for without inspecting 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?

It clearly states when to use this tool—for the global hotspot view and per-domain reviews—and contrasts it with node-local tools as complementary rather than substitutable. It does not list specific sibling alternatives by name for exclusion, but the context and scope/exclude guidance give strong directional usage cues.

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 no annotations present, the description carries the full disclosure burden and does a strong job: it lists what the JSON contains, warns that listings are capped and packages_omitted may appear, and explains a non-obvious omission (entry points) plus its rationale. It stops short of explicitly stating whether the operation is side-effect-free or how it behaves on an empty/missing graph, but the delivered context is well above the baseline.

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

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

The description is front-loaded with the most important guidance — where to start and what it returns — and every sentence adds value, from the cap behavior to the deliberate omission of entry points. It is compact for the amount of context it conveys and keeps the agent's workflow front and center.

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

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

Given that an output schema exists and the parameters are fully documented, the description covers the remaining decision-relevant context: what to expect, how to route results into sibling tools, that listings are bounded, and why certain data is intentionally absent. An agent has enough to call this tool correctly and interpret its output meaningfully.

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 input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds useful context about how returned prefixes connect to other tools, but it does not clarify depth, limit, or db_path semantics beyond what the schema already states. Since the schema covers all parameters, this is an appropriate score.

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 concrete definition — 'sizes and a package map' — and clearly states the tool's role as the starting point in an unfamiliar graph. It names the exact outputs (symbol counts, file/edge totals, unresolved-edge ratio, largest packages) and explicitly frames itself against the other cgis_* tools by saying it is the one that provides the names they need. This is a specific verb+resource with clear differentiation.

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

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

The description gives an explicit when-to-use rule: 'Call this first in an unfamiliar repository.' It also explains the workflow relationship by stating that every other tool needs a name and pointing out that each returned prefix feeds into cgis_get_structure, cgis_find_symbol, or cgis_metrics. It even includes a deliberate exclusion — entry points are not reported — with reasoning, which helps an agent avoid misinterpreting missing incoming edges.

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?

No annotations are provided, so the description carries the full burden, and it delivers: it discloses the exact return payload (modularity_q, divergence, direction, verdict, communities, bridge edges, thresholds), the default graph layer, and the mis-rooted-graph fallback (returns no_signal with a diagnostic note rather than a silent clean verdict). This is strong behavioral disclosure.

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

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

The description is front-loaded with the core purpose, then a compact return-value summary, then the default-layer and prerequisite notes, ending with a one-line caveat. Every sentence earns its place with zero 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?

An output schema exists, and the description still explains the returned JSON fields and verdict values, names the prerequisite tool, and covers the failure mode (mis-rooted graph). An agent has everything needed to call it correctly; the only minor gap is not describing the shape of the communities/bridge-edge entries, but the output schema presumably covers that.

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 practical value: it flags that prefix is 'Needed in practice: without it the verdict is no_signal' and warns that relative db_path resolves against the MCP server's working directory. These notes go 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?

The description states a specific verb and resource ('Suggest sub-package boundaries for a package from its dependency communities') that clearly distinguishes this from siblings like cgis_ingest (graph construction), cgis_drift, and cgis_metrics. An agent can tell at a glance this is the community-detection/refactoring advisor.

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 prerequisite ('Run cgis_ingest first') and explains the default layer (IMPORTS) with how to switch it (with_calls). It doesn't enumerate exclusions or alternative tools, but the when-to-use context is clear and actionable.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that containment edges are excluded by default, that stdlib/third-party/unresolved nodes are excluded unless flags ask for them, that output_format='mermaid' is the default and 'json' returns a joinable payload with real FQNs, and that coverage counts calls that resolved to nothing. It also warns about interpreting top_unresolved ('Read the names, not only the ratio'). The only minor gap is that it doesn't explicitly state the operation is read-only, but the description's framing as a traversal/query makes that reasonably clear.

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

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

The description is dense but well-organized: the core definition is front-loaded in the first sentence, followed by edge-type details, then sibling routing, then output format details. Every sentence earns its place. It is longer than the HIGH calibration example, but the tool is more complex (6 params, multiple output formats, sibling relationships), so the length is justified. It loses one point for being somewhat dense in the middle section where edge types and exclusions are packed together.

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

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

Given the tool's complexity (6 parameters, two output formats, multiple sibling relationships, and a database prerequisite), the description covers everything an agent needs: what the tool does, when to use it, what the output formats return, how to interpret the coverage field, and the prerequisite (cgis_ingest). The output schema exists, so return values need not be spelled out. The description is complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds value beyond the schema by explaining the semantics of the output_format values ('mermaid' for human-readable diagram, 'json' for agent/CI use with real FQNs), clarifying what include_external covers ('stdlib, third-party and unresolved call targets'), and noting that coverage/top_unresolved still counts dropped calls in json mode. It also explains the depth parameter's edge types. This goes beyond the baseline 3 for full schema coverage.

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 precise definition: 'Downstream subgraph of one FQN: everything it reaches within depth hops.' It names the specific verb (trace), the resource (downstream subgraph of one FQN), and the edge types followed. It also explicitly distinguishes itself from siblings: cgis_analyze_impact for reverse dependencies, cgis_get_structure for members only, and cgis_context for a source-included brief. This is a model of sibling differentiation.

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

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

The description gives explicit when-to-use guidance: 'this answers "what does X depend on?"' and then names the alternatives with their conditions: 'For what depends on X use cgis_analyze_impact; for only the members of a module or class, cgis_get_structure; for a source-included brief to read before editing one symbol, cgis_context.' It also tells the agent to run cgis_ingest first if the database does not exist yet. This is complete usage 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?

No annotations are present, so the description carries the burden of behavioral disclosure. The word 'Report' and the output description imply a read-only diagnostic, but the description never explicitly states that the tool does not modify the graph or database, nor does it mention permissions, failure modes, or side effects. Partial transparency at best.

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?

Two compact sentences, with the core purpose front-loaded and the usage guidance in the second sentence. Every word adds value, and there is no filler or repetition of schema details.

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 a full output schema and 100% parameter coverage, the description supplies the essential usage trigger and output flavor. It could be more complete by explicitly stating that the tool is non-mutating, but the read-oriented language and existing schema are sufficient for an agent to invoke it correctly.

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

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

Parameter schema coverage is 100%, with db_path and threshold already well documented. The description adds some interpretive value by linking 'high unresolved ratio' to missing callers, which gives context to the threshold parameter, but it mostly restates what the schema already conveys. This meets the baseline of 3.

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

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

The description opens with a specific verb and resource, 'Report graph integrity as JSON: edge resolution stats + health verdict', which clearly states what the tool produces. It also differentiates itself from siblings by positioning itself as a pre-check for cgis_analyze_impact, so an agent can tell when to pick this 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 provides explicit usage context: 'Check this before trusting cgis_analyze_impact output' and explains the consequence of a high unresolved ratio. However, it does not mention when to avoid this tool or point to alternative validation workflows, so it falls short of full when/when-not coverage.

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