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 does: it discloses traversal exclusions (containment, stdlib/third-party, tests), the file-import boundary rule, max_nodes truncation with 'nearest first' and the truncated flag, the excluded_tests count, and the coverage/top_unresolved upper-bound caveat with the reason (common-name collisions). That is unusually complete behavioral detail for a graph walker.

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?

Information-dense and roughly front-loaded (core definition first, siblings near the end, output formats last), but the prose is long and relies on stacked clauses and parentheticals; some parenthetical caveats could be trimmed without losing meaning.

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

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

For an 8-parameter graph-analysis tool with no annotations, the description covers traversal semantics, exclusions, truncation behavior, output shapes, and the meaning of coverage/top_unresolved; an output_schema exists, so return-format explanation is a bonus rather than a requirement. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining what each flag actually changes in the result set (include_structure follows CONTAINS/DECLARES, include_external adds runtime-resolved targets, include_tests is counted in excluded_tests, output_format=json yields a joinable {root,nodes,edges,coverage} payload enabling set-difference queries).

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

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

The first sentence states a precise verb+resource+scope ('Upstream subgraph of one FQN ... within depth hops') and the second names the exact edge types traversed, so the agent knows this computes reverse dependencies ('what breaks if I change X?'). It also distinguishes itself from cgis_trace_flow (dependencies), cgis_get_structure (members) and cgis_context (editing brief).

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

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

Explicit routing: 'For what X depends on use cgis_trace_flow; 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.' Defaults (tests, external, structure excluded) are stated with the reasons and the same view as the CLI's `impact`, so when-to-use and when-not-to-use are both covered.

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

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

With no annotations the description carries the full burden and does so: it discloses that reachability follows CALLS *and* FastAPI Depends() DEPENDS_ON edges, that depth overrun is reported as a gap, the exact JSON shape ({target, covered, gaps}), and the non-obvious behavior that an empty selection returns a ❌ message rather than a misleading empty-but-passing result. These are genuine behavioral traits 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?

The headline constraint is front-loaded and the paragraphs are tightly scoped to selection, edge semantics, and error behavior. It is on the longer side with some markdown emphasis, but each block 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-param audit tool with an output schema but zero annotations, the description covers the missing pieces: graph edge semantics, selection requirements, depth behavior, and the failure case. An agent can call this correctly without opening anything else.

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

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

Schema coverage is 100%, so 3 is the baseline. The description adds real value on top: it imposes the 'at least one of from_type/from_prefix is required' constraint that the schema (which lists only target as required) does not capture, and explains the ROUTE_HANDLER role semantics and whole-dot-segment prefix matching.

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 line states a specific verb and resource — 'Reachability/authorization audit — which sources never reach a checkpoint' — and immediately narrows to the flagship use case (IDOR/authz coverage). It is clearly distinguishable from siblings like cgis_trace_flow and cgis_analyze_impact because it audits coverage gaps rather than tracing a flow or impact.

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

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

It gives a clear when-to-use anchor ('the headline use is IDOR/authz coverage: list every route handler that does NOT transitively reach an ownership check') and explains how to repurpose it for validators, event tracking, or service-layer boundaries. It does not name sibling tools to route against, so it stops short of explicit alternatives.

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, the description carries the full burden and does so: it discloses the data-key prerequisite (graph ingested with data_keys=True), the degraded behavior when keys are absent, that test-file sites are counted not listed, that common keys are omitted, and a measured precision caveat (~a quarter of data-key items worth a look). These are exactly the operational traits an agent needs before trusting output.

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

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

The core idea is front-loaded in the first sentence, and most sentences carry distinct operational information. It is dense and long with some run-on clauses, but there is little that could be dropped without losing a real constraint.

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

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

An output schema exists, so return values need not be explained, and the description still covers prerequisites, edge cases (empty list, missing data keys), scope limits (test files, common keys) and interpretation guidance. Nothing an agent needs to call or trust the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents cap, base, head, prefix, db_path and output_format, making 3 the baseline. The description adds little parameter-level syntax beyond mentioning the base text is read for removed symbols, so it does not rise above 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 description states a specific verb+resource: it lists what else depends on lines a diff changed (subclasses, callers, data keys). It clearly distinguishes itself from siblings by naming cgis_analyze_impact as the follow-up for judging a site and cgis_ingest for building the required graph.

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

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

It explicitly says when to call it ('before review or merge') and when its output is insufficient ('an empty list means no static dependants were found, not that the change is safe'). It routes the agent to cgis_analyze_impact for the decision a caller makes, giving both when-to-use and an alternative.

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, the description carries the burden and does disclose ranking semantics (exact > prefix > substring), the returned JSON shape, kind filtering, and an unusual prefix-resolution quirk where a directory-style prefix is read without ingested path segments. It never explicitly states read-only/no-mutation behavior, but for a symbol lookup that is low risk.

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

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

Front-loaded with purpose and workflow position, then parameters, then the prefix caveat. Efficient overall, though the final sentence about prefixes starting with ingested directories is awkwardly worded and takes a second read.

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

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

An output schema exists, so return values need no elaboration, and the description still summarizes them. Usage, filtering and the prefix quirk are covered; only the read-only nature and any cost/rate characteristics are absent, which is minor for this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: how kind narrows node types, how fqn_prefix scopes the search, and the non-obvious prefix-vs-ingest-directory interaction. The limit parameter is left to the schema, which already documents it.

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

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

States a specific verb (resolve) and resource (partial symbol name -> candidate FQNs), plus the matching strategy (substring, ranked). It explicitly names the sibling tools it precedes, so an agent can place it in the workflow without opening any schema.

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

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

Gives an explicit precondition: call this BEFORE cgis_trace_flow / cgis_analyze_impact / cgis_get_structure when you know a short name but not its FQN. It also states the payoff (removes read-the-file-first guesswork), leaving nothing to inference.

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

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

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, the description carries the full burden and does so well: it discloses that only CONTAINS/DECLARES edges appear, that packages are not real graph nodes (#487) so their rows and edges are synthesized and marked with a virtual file path. 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, followed by containment caveats, routing guidance, and format notes in a logical order. It is slightly verbose in re-describing output_format, which the schema already covers, but no sentence is truly wasted.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description still covers containment semantics, package virtualization, and format choices. Combined with 100% schema coverage, an agent has everything needed 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 description coverage is 100%, so the schema already documents fqn, depth, db_path, and output_format. The description's output_format gloss largely restates the schema entry rather than adding syntax or format detail beyond it, so the baseline 3 applies.

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

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

The opening sentence states a specific verb and resource: the members of a module or class, or the modules held by a package prefix. It distinguishes itself from siblings by explicitly noting it follows containment only, and names the alternatives for connectivity queries.

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 routes the agent explicitly: use cgis_trace_flow for what the code depends on and cgis_analyze_impact for what depends on it, leaving no inference about when not to use this tool. The CLI parity note ('Matches the CLI structure command') further anchors context.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the incremental-by-default model, the automatic whole-graph rebuild triggers (renamed/removed/added symbols, deleted/new files, changed base class or re-export), the full_rebuild override, the cost of data_keys in time and graph size plus its staleness side effect on JSON/YAML edits, and the constraint that parent directories will not be created.

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

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

Front-loaded with purpose, then conditions, then the incremental/full-rebuild distinction and the data_keys caveat — a sensible ordering with no filler sentences. It loses a point because the db_path restrictions are restated almost verbatim from the schema rather than summarised once.

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

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

An output schema exists, so return values need no explanation. Against a 4-parameter mutation-style ingest tool with zero annotations, the description covers process, incremental semantics, rebuild triggers, opt-in features and failure conditions — nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the consequences of data_keys (cost, staleness, mode inheritance, rebuild-on-switch) and the semantics of full_rebuild rather than just restating the flag. The db_path paragraph largely duplicates the schema, keeping this just above baseline rather than clearly exceptional.

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

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

The first sentence names a specific verb chain and resource: scan a directory, extract symbols, resolve links, build the graph DB. That is clearly distinguishable from the read-only analysis siblings (cgis_find_symbol, cgis_analyze_impact, cgis_overview), which the agent can tell apart 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?

"Use this to initialise or refresh the code knowledge graph for a project" gives clear context, and the data_keys note routes the agent toward cgis_diff_check when that feature is needed. However, it never states when NOT to use this tool versus an analysis sibling, nor prerequisites like having a workspace already in place; the guidance is contextual but not exclusionary.

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 the description carries the full burden and does so thoroughly: it discloses transitive reduction rules, that cycle-closing edges are never dropped, that test modules and type-only imports are excluded, that external dependencies are summarised rather than drawn, and how `covered` should be interpreted.

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 the content is dense and useful, but the cycle rule is stated three separate times ("never dropped", "always drawn", plus the `covered` aside), and the json return shape is spelled out despite an output schema existing.

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

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

For a 7-parameter analysis tool with a full schema and an output schema, the description covers the prerequisites, exclusions, reduction semantics and output modes well; it only omits failure behaviour for an unknown prefix or missing database.

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 every parameter is already documented in the schema, including the same expand/reduce/cycles semantics the description restates; the description adds marginal interpretive value (e.g. that calls make the picture denser) rather than new parameter meaning.

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

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

The opening sentence names a specific resource (a package's internal module/dependency graph) and the description then pins down exactly what nodes and edges represent, so an agent can distinguish it from package-level siblings like cgis_overview or cgis_get_structure without opening the schema.

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

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

It gives one hard prerequisite ("Run cgis_ingest first") and notes that `expand` lists every module instead, but never says when to choose this over alternative structural tools such as cgis_overview or cgis_fractal, and offers no when-not guidance.

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

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

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?

With no annotations, the description carries the whole burden and does so: it discloses that containment edges are skipped by default, that tests/external/unresolved targets are dropped by default, that results are truncated at max_nodes with the walk stopping mid-level, that rounded coverage counts can be misleading in Python, and that an unknown output_format returns an error. That is unusually rich behavioral context for an analysis tool.

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

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

Front-loaded: the first sentence defines the tool, then routing to siblings, then option semantics. However, it re-explains several parameters (output_format, max_nodes, include_tests) that already have 100%-covered schema descriptions, adding length without new information. Still readable and every section is relevant.

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, return-shape detail is optional, yet the description clarifies the json payload ('joinable {root, nodes, edges, coverage}'), what coverage counts and how to read top_unresolved. Combined with edge-type and default-exclusion coverage, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by giving the tradeoff behind output_format ('about a fifth of the json for the same answer'), explaining that max_nodes truncation reports where the cut fell, and clarifying that include_external covers stdlib, third-party and unresolved call targets. It largely restates rather than extends the schema on the boolean flags, so it is above baseline but not maximal.

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

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

Opens with a specific verb+resource and scope: 'Downstream subgraph of one FQN: everything it reaches within depth hops.' It then enumerates exactly which edge kinds are followed and which are excluded, and explicitly names the sibling tools for adjacent questions (cgis_analyze_impact, cgis_get_structure, cgis_context). An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit routing rules: '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... cgis_context.' It also states the prerequisite ('Use cgis_ingest first if the database does not exist yet') and the default-exclusion conditions that select the include_* flags.

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

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

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.