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, the description carries the full burden and delivers: it names the graph relationships that count as a use, discloses the default hiding of generated and nested classes with measured justification, and warns 'a listing is a candidate for deletion, not a proof' with the specific blind spots (decorator-only references, star imports). It even documents staleness signals such as test_sources: 0 meaning a pre-is_test graph that needs re-ingestion.

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 correctly, but the description runs several hundred words and includes anecdotal evidence ('43 of 1 789 classes', 'five of six reported orphans were generated entities') and issue citations that read as justification prose rather than invocation guidance. Much of the length is defensible behavioral disclosure, but the anecdotes could be trimmed without losing selection value.

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

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

For a 5-parameter analysis tool with subtle semantics, the description covers the detection model, default exclusions, caveats about false negatives, and failure modes in the backing data. An output schema exists, yet the inline description of the returned JSON keys adds interpretive context (what a 0 in generated_excluded implies) that the schema alone would not convey.

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 prose adds real meaning beyond the schema: prefix cuts on a dot boundary to one package, include_tests redefines the report as 'unreachable from anywhere', and include_generated/include_nested are given the rationale for their defaults. Only db_path (covered adequately by the schema) is unaddressed.

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 states a specific verb and resource — 'Classes nothing in production builds, extends or names — dead-code candidates' — and the detail about CALLS/EXTENDS/REFERENCES usage makes the target precise. No sibling tool in the cgis_* family overlaps with orphan detection, so an agent can select this unambiguously.

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 strong context on when the output is meaningful vs. noise: tests-as-users, re-exports, generated classes, and nested classes are each explained with the interpretation they enable. What it lacks is an explicit routing statement against alternatives (e.g., cgis_analyze_impact or cgis_audit_reachability), so it earns a 4 rather than 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 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 richly: it discloses the optional duckdb dependency and its ❌ error path, explains that scope vs exclude differ because exclude removes nodes from PageRank propagation while scope only filters rows, and clarifies that resolution affects how rankings should be read. These are exactly the non-obvious behaviors an agent needs.

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

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

Purpose is front-loaded and each section explains a real output key or parameter behavior, so most sentences earn their place. It is dense and slightly over-long, with some overlap against the already-descriptive schema for scope/exclude.

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?

Complete for this tool: an output schema exists so return values needn't be re-explained, no annotations need compensating, and the description covers dependency requirements, parameter interactions, and ranking interpretation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: anchored dot-boundary matching ('domains.reservation' not 'domains.reservation_archive'), dot-segment containment for exclude, and the semantic divergence between the two flags for PageRank and coupling in-degree.

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+resource and enumerates the concrete outputs (coupling bottlenecks, God classes, PageRank), then explicitly positions it as 'the global what-are-the-hotspots view that complements the node-local trace/impact/context tools.' An agent can distinguish it from cgis_trace_flow/cgis_analyze_impact/cgis_context 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 clear context: use it for whole-graph hotspot analysis, and the scope/exclude paragraph tells the agent to reach for it during a 'per-domain review.' It routes between scope and exclude well, but stops short of explicit when-not conditions or naming a specific sibling to avoid.

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?

With no annotations, the description carries the full burden and does so: it discloses the JSON payload shape, the default layer, the recursive all_descendants mode, and notably the failure mode that a mis-rooted graph returns no_signal with a diagnostic note rather than a silent clean verdict. That edge-case disclosure is exactly the kind of behavior an agent needs before trusting the output.

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

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

Front-loaded with the purpose, then the return shape, then the configuration and precondition. Efficient overall, but the detailed return-field enumeration duplicates what the output schema already carries, which is some wasted space.

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?

Preconditions (cgis_ingest first, prefix needed in practice) and failure behavior are covered, which is what the agent needs to call it correctly. Since an output schema exists, the lengthy return-value listing is partly redundant but not harmful.

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 parameters (min_q, prefix, db_path, with_calls, all_descendants) are already documented in the schema. The description mostly restates those semantics (with_calls, all_descendants) rather than adding syntax or format detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Suggest sub-package boundaries for a package from its dependency communities.' This is clearly distinguishable from analysis siblings like cgis_metrics or cgis_get_structure, but no sibling is named or contrasted, so it falls short of the top band.

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

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

Gives a clear prerequisite ('Run cgis_ingest first') and the layering choice ('Default layer is IMPORTS; set with_calls for the combined import+call graph'), so an agent knows how to configure it. It never states when to prefer this over a sibling tool (e.g. cgis_fractal), so no exclusions or alternatives are offered.

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.