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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description is consistent with them: "Read-only apart from reading the selected graph or extracting a temporary archive that is removed after the call" clarifies exactly what touches disk and that the archive is cleaned up. It adds real context beyond the annotations (freshness check before the call, refresh in the requested analysis mode, CHA/SSA retry for precise modes), though the sentence about the .json baseline's "linked path component" and "source-policy marker" is too opaque to be actionable.

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

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

Front-loaded with the core action, then clearly labeled WHEN TO USE / NOT TO USE / RETURNS blocks, which makes it quick to scan. It runs long and the middle sentences about .json baselines and precise_fallback retries are dense, though each does carry behavioral information rather than filler.

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

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

For a four-parameter tool with full schema coverage and clear safety annotations, the definition covers purpose, triggers, exclusions, side effects, and the return shape (baseline/breaking flags, added/removed arrays, affected_tests, affected_mocks, findings, and the empty-groups convention). The only shortfall is the unexplained source-policy/linked-component constraint on .json baselines, which an agent cannot act on as written.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bump by explaining the two-mode behavior of `since` beyond the schema text: a .json path loads a saved graph and its serialized root is ignored, while any other value is validated as a Git ref and expanded via git archive into a temporary baseline. The `root` and `session_id` parameters are not discussed in the description, but the schema already covers them thoroughly.

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: "Detect public API surface drift by comparing exported Go symbols between the current working tree and a baseline." It also explicitly names the siblings it is not (gograph_public, gograph_skeleton) for the no-baseline case, so an agent can route correctly 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?

Provides an explicit WHEN TO USE (before releasing or merging a PR to catch breaking-change regressions: exported symbols added, removed, renamed) and an explicit NOT TO USE with the alternative tools named. Both the trigger and the exclusion are stated, 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only; no side effects' largely restates structured data. What does add value is the note that the server checks freshness before the call and the description of the return payload (parameter count, signature, file location), which the agent would otherwise have to infer in the absence of an output schema.

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

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

Front-loaded with the core purpose, then cleanly labeled WHEN TO USE / NOT TO USE / RETURNS blocks, which scan well. Minor waste: the 'Read-only; no side effects' clause duplicates the annotations, and the freshness sentence is vague about what actually happens.

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 four-parameter, no-required-arg analysis tool with no output schema, the definition covers purpose, exclusions, threshold behavior, and return shape, so an agent can call it correctly. The only soft spot is the unexplained freshness-check remark, which does not affect 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 baseline is 3. The description restates the `min` threshold semantics already spelled out in the schema property and adds only the CLI --min correspondence; the root, intention, and session_id parameters are left entirely to the schema.

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

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

States a specific verb and resource ('Find functions and methods with at least a threshold number of parameters') and ties it to a named smell, which tells an agent exactly what class of result to expect. It also distinguishes itself from the nearest similarly-shaped siblings by naming gograph_fields and gograph_godobj as the wrong tool for struct field counts.

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

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

Explicit WHEN TO USE ('During code smell audits') and NOT TO USE clauses with named alternatives make the routing decision unambiguous. This is the highest-value part of the definition given how many gograph_* analysis siblings exist.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description nevertheless adds real context: the config path is confined to the analyzed project, every path component and the final regular file are resolved through the rooted repository boundary, and a missing config should be created via gograph_boundaries_create. It also discloses the return shape ('structured pass state and boundary violations'). It stops short of explaining what 'refresh source analysis' does to the index or whether pagination via limit/cursor matters for violation enumeration.

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

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

Front-loaded with the action, then constraints, then WHEN TO USE / NOT TO USE / RETURNS blocks. Nearly every sentence carries decision-relevant information; the boundary-resolution sentence is the densest and slightly over-explains a constraint the schema also encodes, keeping it from a 5.

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

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

For a six-parameter, all-optional analytic call with rich schema coverage and no output schema, the description supplies the missing decision layer: purpose, trigger context, alternatives, and a one-line return summary. Only minor gaps remain (what the refresh step costs, how violations relate to pagination), which are unlikely to cause a misinvocation.

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

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

Schema description coverage is 100% and each of the six parameters is already documented in depth (root must be this server's repo or a worktree, limit 1-200 with byte budget, config default, cursor semantics, session/intention selectors). The description only reinforces the config parameter's default and boundary constraints, which the schema already states ('in-project', 'regular, non-linked'). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb pair and resource: 'Refresh source analysis and check package imports against a boundaries.json configuration.' It also names the sibling that creates the config (gograph_boundaries_create) and the siblings for unconstrained exploration (gograph_deps, gograph_coupling), so the agent can place it among ~70 tools without opening a schema.

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

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

Explicit WHEN TO USE ('CI gates or post-edit reviews to enforce layer separation') and NOT TO USE with named alternatives ('unconstrained dependency exploration, use gograph_deps or gograph_coupling'). Both the positive trigger and the exclusion are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=false, so 'Mutating and non-idempotent; no network access' largely restates them. The value-add is the disclosed refusal behavior — repository-rooted regular-file creation that rejects linked paths and refuses to overwrite an existing config — which tells the agent how failure modes arise.

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 statement of purpose and default path, followed by labeled WHEN TO USE / NOT TO USE / RETURNS blocks that are easy to scan. There is minor redundancy with the schema on the default path and refusal rules, but no filler.

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

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

No output schema exists, and the RETURNS line supplies the return contract (written config path, or an error when the path is unsafe or already exists). Combined with the adoption workflow guidance, an agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds only the default config path and the refusal rule for the output path, both of which are already present in the 'config' schema text, so it does not meaningfully exceed the schema 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 gives a specific verb and resource ('Create a baseline architecture boundary configuration from the repository's current package imports') and immediately pins down the default output location, so an agent knows exactly what artifact is produced and where it lands.

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

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

Explicit WHEN TO USE ('Once when adopting boundary checks in an existing repository, then review and tighten the generated rules') and NOT TO USE with a named alternative ('use gograph_boundaries' for verification), which cleanly separates it from the sibling tool with a nearly identical name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered; the description still adds a non-obvious behavior not in annotations, namely that the server refreshes source analysis before the call. It also discloses the depth-driven expansion and the mermaid output switch. It does not mention cost/latency of the refresh or pagination behavior under the limit/cursor pair, keeping it short of a 5.

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

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

Four short, labeled segments (core behavior, WHEN TO USE, NOT TO USE, RETURNS) with the primary action and default fan-out front-loaded. No redundant restatement of the tool name and no filler sentences.

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

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

There is no output schema, and the RETURNS section compensates by naming callee symbols, package paths, file locations, call-site line numbers, and the mermaid variant. Combined with the annotation-backed safety profile and the routing guidance, an agent has everything needed to select and 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 description coverage is 100%, so every parameter including root, cursor, session_id and intention is already documented in-schema; the baseline is 3. The description adds only marginal meaning beyond that — clarifying that depth 2-10 expands the graph and that mermaid=true swaps the response format for flowchart text. Useful framing but not compensating for any documented gap.

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

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

States a specific verb and resource ('Find functions and methods called by the specified function') and immediately pins the direction of traversal as downstream fan-out. It explicitly contrasts itself with gograph_callers (upstream) and gograph_deps (package trees), so an agent can discriminate it from siblings without opening any schema.

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

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

Provides an explicit WHEN TO USE ('understand a function's downstream dependencies') and a NOT TO USE clause naming the two alternative tools with the condition that selects each. This is the strongest form of routing guidance in the sibling set.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, yet the description adds real context: default one-hop fan-in, depth 2-10 semantics, interface dispatch expansion through all recorded implementations with a shared source call site reported once, and a pre-call source-analysis refresh. These are behavioral facts not recoverable from structured fields.

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

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

Front-loaded with purpose and default scope, then clearly demarcated WHEN TO USE, NOT TO USE, and RETURNS segments. Every sentence carries information; nothing is redundant with the schema or annotations.

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 10-parameter analysis tool with no output schema, the description covers the return shape (caller symbols, package paths, file locations, call-site line numbers, Mermaid alternative), the default depth, and the interface-expansion edge case. The remaining parameters are fully documented in the schema, so nothing an agent needs 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 3 is the baseline, and the description earns a bump by explaining what depth actually does (2-10 expands callers-of-callers vs. the default one-hop) and that mermaid switches the response to flowchart text. It does not add meaning for root, cursor, limit, no_tests, or session parameters beyond the schema.

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

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

The opening sentence gives a specific verb and resource: 'Find functions and methods that call the specified function or interface method.' It immediately distinguishes itself from the sibling gograph_callees (which returns the opposite direction) and from gograph_impact (which handles broader blast radius).

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

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

Explicit WHEN TO USE (before renaming, removing, or changing a signature) and NOT TO USE clauses naming both alternatives with the condition that selects them (unbounded upstream blast radius → gograph_impact; downstream callees → gograph_callees). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description nonetheless adds the non-obvious prerequisite that no graph state is needed once the server is up, plus the caching guidance. It partially restates the read-only/no-side-effects claim already in annotations, and does not discuss cost or size of the returned catalog, which keeps it below a 5.

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

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

Front-loaded purpose sentence followed by labeled WHEN TO USE / NOT TO USE / RETURNS blocks that scan well. Minor waste: 'Read-only; no side effects' duplicates the annotations, and RETURNS restates the version/tool-list already given in sentence one.

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 zero-required-parameter orientation tool with no output schema, the description supplies the return shape (version, tool names, one-line purposes, workflow sequences, known limitations), the prerequisite, and the calling cadence. Nothing an agent needs before calling 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% with all three optional parameters fully documented in-schema (root, intention, session_id), so the baseline of 3 applies. The description says nothing about these parameters — notably it omits that root scopes the answer to a checkout — but the schema already carries that 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?

States a specific verb and resource set: lists the server version, every registered MCP tool, their purposes, and recommended workflows. This is clearly a meta/introspection tool, which no sibling (gograph_callers, gograph_explain, etc.) duplicates, so an agent can place it immediately.

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

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

Provides explicit WHEN TO USE (once per session to record the instrument and orient before analytical queries) and NOT TO USE (do not repeat after capabilities are cached) sections, plus a stated prerequisite — the project-scoped server must have started. Timing and exclusion are both unambiguous.

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

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

Well beyond the annotations, which already cover read-only/idempotent/no-destructive: the description discloses the two operating modes (no git_ref reads persisted graph.json without refreshing; with git_ref refreshes), that no application code is compiled, that deselected files are excluded rather than deleted, that parse failures yield diagnostics and never deletion proof, and that missing legacy fingerprints resolve to unknown. It also states refusal behavior for unsafe inputs and the exit-2 convention for incomplete evaluation.

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

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

The purpose is front-loaded and the WHEN/NOT/RETURNS structure is helpful, but the middle is a wall of compressed fragments ('confined declaration baseline', 'Traversal consumers refuse deleted declarations requiring historical caller evidence') that read as internal design notes rather than agent-facing guidance. Several sentences could be merged or dropped without losing actionable information.

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

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

With no output schema, the description does the right thing by enumerating the return shape (complete/partial/cannot_evaluate, diagnostics, changed_files, symbol row categories) and the incomplete-evaluation failure modes. A few concepts — what a 'confined declaration baseline' is, and what distinguishes 'excluded' from 'unknown' in practice — remain underspecified for a tool with this many modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: git_ref's presence switches the tool between a no-refresh artifact read and a refresh, and root scoping determines which checkout's graph answers. intention and session_id are left entirely to their schema text, which is acceptable given the full 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 opening sentence states a specific verb and resource — 'Compare Go declaration fingerprints, including bodies' — and immediately distinguishes the semantics from line-level diffing ('without marking every symbol in an edited file modified'). The jargon 'fingerprints' and the dense follow-on sentences make the agent work harder than necessary to confirm the core operation, but the operation is unmistakably identifiable.

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

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

Explicit 'WHEN TO USE' (after editing, before impact/review) and 'NOT TO USE' (line-level diffs; complete census when evaluation is partial) sections are present, plus a routing note pointing to review for changes --git HEAD evidence. It never names the actual sibling tool identifiers (gograph_review, gograph_impact), so the agent must infer the mapping, and the NOT-TO-USE clause is phrased awkwardly enough to require re-reading.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description still adds real behavior: config path confinement rules, how baselines are validated (in-project .json with policy marker, otherwise treated as a Git ref), that serialized root is ignored, that incomplete comparisons and ambiguous identities are errors, and that a rebuild is needed before traversing new symbols. Some of the mid-text sentences ('Traversal consumers refuse deleted declarations... Review instead includes changes --git HEAD...') are cryptic and hard for an agent to act on.

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 WHEN TO USE / NOT TO USE / RETURNS markers give useful skeleton, but ordering is poor: path-validation and baseline-builder rules precede the usage section and belong with the parameters. Several sentences are jargon-dense and some, like the traversal/historical-caller passage, consume space without helping an agent decide or invoke.

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

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

For a complex aggregate with no output schema, it covers scope, return shape (pass/warn/fail status, findings, summary counts), error conditions, and uncommitted-mode semantics. What is missing is a clear statement of what the checks config controls and how results are grouped, but overall an agent has 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 description coverage is 100%, so every parameter is already documented in the schema, making 3 the baseline. The description partially restates config and since semantics and adds one genuine detail (the saved graph's serialized root is ignored), but it adds no new meaning for root, intention, session_id, or uncommitted.

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 compound action ('Refresh source analysis and run static policy checks') and enumerates the concrete check families it aggregates (boundaries, API drift, coverage, orphans, globals, arity, complexity). An agent can immediately tell this is the aggregate policy-run tool rather than any single sibling like gograph_boundaries or gograph_arity.

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 WHEN TO USE (PR review, pre-commit) and NOT TO USE with a named alternative ('use CLI gograph gate' for CI exit enforcement), which is unusually strong routing guidance. It does not say when to prefer this aggregate over the individual sibling tools (gograph_coverage, gograph_orphans, etc.), which is the one ambiguity left.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description goes well beyond that by disclosing sort order, the severity taxonomy, the UNKNOWN/-1 sentinel for unreadable or unparseable repository source, and a freshness check with refresh plus CHA/SSA retry under precise/precise_fallback modes. These are non-obvious behaviors an agent could not infer from the annotations, and none of them contradict the declared read-only, idempotent nature.

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 well front-loaded: purpose, then the UNKNOWN edge case, then WHEN/NOT TO USE and RETURNS blocks. The one soft spot is the dense mid-paragraph sentence about freshness checking and CHA/SSA retry, which packs internal implementation jargon into a run-on clause that an agent must parse to extract the actionable point (results are fresh and safe to trust).

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

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

With no output schema, the description carries the return contract and does so: a structured list of functions with complexity score and severity label, sorted descending, empty when the filter matches nothing, plus the -1/UNKNOWN sentinel. Given four optional parameters, full schema coverage, and complete safety annotations, nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 per the rubric. The description restates the `symbol` substring behavior ('filters to a specific function or set of functions') without adding format or matching semantics beyond what the schema already says, and it never mentions `root`, `intention`, or `session_id`, leaving those entirely to the schema — which does document them adequately.

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 verb and resource — 'Report estimated cyclomatic complexity for Go functions' — and immediately states the output ordering and severity labeling. The NOT TO USE block names the exact siblings to route away to (gograph_coupling, gograph_deps for import metrics; gograph_godobj for God Objects), so an agent can separate this tool from a large family of similarly named gograph_* tools without opening a schema.

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

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

The description provides an explicit WHEN TO USE list (quality audits, decomposition candidates, CI complexity budgets) and an explicit NOT TO USE list with the alternative tool named for each excluded case. This is the strongest form of routing guidance: both the positive trigger and the negative trigger are stated, leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description only restates 'Read-only; no side effects', which earns no credit. It does add real behavior beyond annotations: a server-side freshness check with refresh in the current analysis mode, CHA/SSA retry on precise graphs after source changes, an empty result when nothing is indexed, and the indexing gaps for receives/selects. Pagination hint ('next_cursor for the same graph snapshot') lives in the schema rather than the description, which keeps this from a 4-5.

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

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

Front-loaded with the purpose, then cleanly delimited WHEN TO USE / NOT TO USE / RETURNS blocks that are easy to scan. The `term` example is redundant with the schema, and the freshness/CHA-SSA sentence is dense, but no sentence is filler.

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

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

No output schema exists, and the description compensates with a RETURNS section giving file locations, line numbers, primitive kind, and empty-when-none semantics. With six optional parameters at full schema coverage and the freshness/refresh behavior disclosed, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's only parameter content is 'Optional `term` filter (e.g., "mutex", "goroutine", "channel")', which duplicates the schema's own examples almost verbatim; no added meaning for root, limit, cursor, intention, or session_id.

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?

Names a specific verb and resource ('Find indexed concurrency sites') and enumerates exactly what counts as a site: `go` statements, channel sends, and calls on sync.Mutex/RWMutex, WaitGroup, and Once. It also states negatives (channel receives and selects not indexed), which lets an agent predict results without trial calls.

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

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

Explicit 'WHEN TO USE' (race safety audits, async flow, pre-refactor synchronization mapping) paired with an explicit 'NOT TO USE' that names the sibling alternatives gograph_callers/gograph_callees for sequential flow. The agent has a direct routing rule between this tool and its nearest substitutes.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the description's "Read-only; no side effects" is redundant, but it adds genuinely non-structured behavior: the server checks freshness before the call, refreshes into the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. That is useful operational context an agent would otherwise not know; it stops short of discussing cost/latency of the re-analysis.

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

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

Front-loaded with the core definition, then clearly delimited WHEN TO USE / NOT TO USE / RETURNS blocks, so it scans fast. The freshness/retry sentence is somewhat dense jargon and could be one clause shorter, keeping it just below maximum.

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 6-parameter, read-only query tool with no output schema, it covers what is found, how matches are defined, when to prefer siblings, that results can be empty, and the return shape (names, signatures, package paths, file locations). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds matching semantics the schema does not carry: the struct is identified by appearing in a function's return type, and results are empty when no factory is found. It still says nothing extra about root, cursor, limit, session_id, or intention, which the schema already documents.

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

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

"Find all factory and constructor functions that instantiate and return a named Go struct" gives a specific verb plus a precise resource definition, and the parenthetical even states the matching rule (return type includes the struct name). It explicitly names the two nearest siblings it is not (gograph_literals, gograph_fields), so the agent can disambiguate 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?

Provides an explicit WHEN TO USE section with a concrete scenario (finding the canonical construction path, or before changing struct initialization) and an explicit NOT TO USE section routing to gograph_literals for composite literals and gograph_fields for fields. Symmetric when/when-not with named alternatives is the top of this scale.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is given. The description still adds real behavioral context beyond them: freshness checking/refresh of precise and precise_fallback graphs, possible local command telemetry during an active audit session, partial-context source_error with graph_state.read_diagnostic, and refusal to traverse deleted declarations. Some of this is dense jargon (CHA/SSA retry) rather than actionable agent guidance, so it stops short of the top score.

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?

Strongly front-loaded: purpose first, then WHEN TO USE, NOT TO USE, and RETURNS sections. The RETURNS block, however, is a wall of run-on edge-case clauses ('Traversal consumers refuse deleted declarations requiring historical caller evidence', 'Incomplete comparisons and missing/ambiguous current identities remain errors') that cost more parsing effort than they repay.

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

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

No output schema exists, so the description carries the return contract itself and does so thoroughly: node/nodes[], source, callers[], callees[], tests[], test_results[], role in text and gograph.read.v1, the contexts[] variant, and the named error/diagnostic paths. It also flags the rebuild prerequisite for newly added symbols, leaving little an agent needs before calling.

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 still adds meaning the schema does not — uncommitted=true compares declarations against HEAD including selected untracked files and returns a contexts[] array with count:0 when nothing is modified, and it notes that missing symbols are named errors while exact controls matching strictness. root/session_id/intention semantics are left entirely to the schema.

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

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

Opens with a specific verb and resource ('Fetch a pre-flight context bundle for a single Go symbol') and enumerates exactly what the bundle contains (AST metadata, source, callers, callees, tests, role classification). This is clearly distinguishable from siblings like gograph_node or gograph_source that return single facets.

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

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

Explicit 'WHEN TO USE: As the first call before editing a symbol — eliminates 4–5 separate tool roundtrips' plus a 'NOT TO USE' clause that names the correct alternatives and their conditions (gograph_focus for package orientation, gograph_impact for transitive blast radius). Routing is fully determined.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so 'Read-only; no side effects' adds nothing. The genuinely useful addition is that the server refreshes source analysis before the call, which signals freshness and latency cost, plus the note that coupling returns Mermaid text when mermaid=true.

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 metric definition, then scope controls, then WHEN TO USE and RETURNS blocks. Efficient, though 'Read-only; no side effects' duplicates the annotations and is wasted space in an otherwise dense description.

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 seven optional parameters and no output schema, the description covers what is measured, scope controls, and the return format including the Mermaid variant. The main gap is that the session_id/intention parameters, which are non-obvious for analytical calls, get no mention in the description.

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 restates the surface semantics ('package filters by substring; include_stdlib and internal_only control scope') but does not add the nuanced relationship between internal_only and include_stdlib that the schema spells out, nor anything about root, session_id, or intention.

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

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

States a specific verb and resource with named outputs: fan-in (Ca), fan-out (Ce), and instability I=Ce/(Ca+Ce) per package. It does not name overlapping siblings such as gograph_deps, gograph_imports, or gograph_boundaries, so the agent must infer the distinction from the definitions of those tools.

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

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

The 'WHEN TO USE: To evaluate package isolation' line gives a usage context but no exclusions or named alternatives, despite several siblings (gograph_deps, gograph_imports, gograph_boundaries) that could plausibly serve similar needs. The agent is told when, but not when not.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that the server refreshes the graph first, that parser-only or CHA edges downgrade a symbol and its descendants to possible, that same-named tests yield status=ambiguous and are never merged, and that package disambiguates foo_test collisions. These are genuinely useful behavioral traits. Minor deduction for the redundant 'Read-only; no side effects' restating the annotations.

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

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

Content is front-loaded with the core definition followed by precision semantics, disambiguation, and labeled WHEN/NOT/RETURNS blocks. It is dense but nearly every sentence carries information; the trailing 'Read-only; no side effects' is the one line that duplicates structured annotation data rather than adding to it.

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?

This is a complex analytical tool with six parameters and no output schema, and the description still covers precision model, ambiguity handling, exclusions, and the returned gograph.coverage.v1 field set. Nothing an agent needs to invoke or interpret 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: the purpose of package as a narrow disambiguator for the in-package versus external foo_test collision, and the effect of exact_only=true in omitting possible results. The root parameter is left entirely to the schema, which is acceptable but the only unaddressed surface.

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, resource, and scope: the transitive set of production symbols statically reachable from one test function. It is clearly separable from siblings like gograph_tests, gograph_untested, and gograph_trace, and the WHEN TO USE line reinforces the distinction.

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

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

Explicit WHEN TO USE and NOT TO USE sections state the positive case (map a test to structurally exercised symbols) and the exclusion (do not claim runtime or branch coverage). It also routes the agent to alternatives on ambiguity, telling it to retry with stable IDs from matched_tests or gograph_identity, and explains when to set exact_only.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the 'read-only; no side effects' line is somewhat redundant. The value-add is the disclosure that the MCP server refreshes source analysis before the call and that mermaid=true changes the response format entirely. Pagination mechanics are left to the schema rather than described.

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?

Labeled WHEN/NOT/RETURNS structure is easy to scan and the identity statement is front-loaded. Slightly verbose in places ('Read-only; no side effects' repeats the annotations) but no sentence is wasted filler.

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

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

For a 7-parameter read-only query tool with no output schema, the description covers purpose, entry/exit conditions, result shape, and the analysis-refresh side effect. Missing only result ordering and pagination behavior, which the schema's limit/cursor fields largely cover.

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 only adds meaning for 'mermaid' (returns flowchart text) and 'package' implicitly (accepts 'auth' or a full import path is in schema, not description). Root/limit/cursor/session parameters receive no additional explanation.

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

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

States a specific verb and resource ('find all packages that import the named package') and immediately anchors it relative to a named sibling ('inverse of gograph_deps'). An agent can distinguish this from gograph_deps and gograph_callers without inspecting any schema.

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

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

Explicit 'WHEN TO USE' (before a package-level interface change or removal) and 'NOT TO USE' (single function's callers, route to gograph_callers) sections. Both the positive trigger and the exclusion with a named alternative are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Read-only; no side effects' just repeats machine-readable data. The description does add real context that the annotations cannot convey: the server refreshes source analysis before the call, which implies freshness and possible latency. It also states that the tool returns found:false when the package is absent, which is a useful behavioral note.

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

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

It is compact and front-loaded: purpose first, then the options, then labeled WHEN TO USE, NOT TO USE, and RETURNS sections. Every sentence carries information except 'Read-only; no side effects', which repeats the annotations but is a minor redundancy.

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?

It covers six parameters with full schema coverage, and it spells out both the return shape (direct[] and transitive[] arrays, Mermaid text, found:false) and the main behavioral trait (the server refreshes analysis first). For a read-only query tool with no output schema, 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, and the description adds meaning beyond it: it gives transitive=false as the default and describes its effect (direct imports versus the BFS closure), and it links mermaid=true to flowchart output. The remaining parameters (root, session_id, intention) are fully documented in their own schema 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?

The description names a specific verb and resource ('List the import dependencies of a named package') and immediately distinguishes the tool from gograph_dependents, the reverse-lookup sibling. An agent can pick this one without opening any schema.

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

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

It gives an explicit WHEN TO USE case ('auditing package layering') and a NOT TO USE case that routes the agent to gograph_dependents for reverse lookup. This is exactly the when/when-not/alternative structure that makes a definition selectable.

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?

The annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so "Read-only; no side effects" largely restates structured data. The description does add behavior the annotations cannot express: it returns Mermaid text rather than a file, and it discloses a scale caveat (use max_depth or coarser grouping for large graphs). What it omits is whether "refresh source analysis" triggers an index rebuild and how long that takes, which matters for a tool whose name implies work beyond formatting.

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?

Four sentences, front-loaded with the core action before the labeled WHEN TO USE, NOT TO USE, and RETURNS sections. The labeled structure makes it scannable, and no sentence is filler — even the scale caveat prevents a foreseeable failure.

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 six optional parameters, no required inputs, and no output schema, the description adequately covers purpose, selection, tuning, and return type (Mermaid text). The remaining gap is operational: it never mentions that regenerating analysis may take time or that output size is bounded, leaving the agent to discover volumetrics on large repos by trial.

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?

Every parameter is documented in the schema at 100% coverage, so the baseline is 3 and the schema carries most of the semantic load. The description only adds scenario-level meaning for group_by (module vs file) and max_depth (large graphs); root's worktree constraint, session_id, intention, and include_stdlib are left entirely to the schema.

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

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

The description opens with a specific verb and resource: "Refresh source analysis and generate a Mermaid architecture diagram of the package dependency graph." It also explicitly excludes sibling territory ("call-graph traversal or single-package focus"), so an agent can separate it from gograph_deps, gograph_callers, or gograph_explore without reading any schema.

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

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

It provides explicit positive triggers (onboarding, architecture review, communicating package structure) and explicit negative scope ("NOT TO USE: For call-graph traversal or single-package focus"). It further routes parameter choice by scenario — group_by=module for monorepos, group_by=file for drill-downs — which is decision guidance rather than mere option listing.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, yet the description still adds real substance: it says the handler does not read the graph, requires a started server with a usable artifact, rejects filesystem-shaped queries, and resolves dependencies open-world. The preflight rules are dense and partly opaque ('a special recognized Go build input'), so the added context is valuable but not fully legible.

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 WHEN TO USE / NOT TO USE / RETURNS scaffolding is well front-loaded and scannable. However, the middle is one long run-on enumeration of preflight refusals (source-tree links, .git/.gograph exclusions, go.mod/go.sum/go.work, workspace member boundaries) that costs far more reading effort than it returns for a fetch-doc tool.

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

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

No output schema exists, but the description compensates by specifying the return shape ({query, output} in a one-element array) and the error conditions (unsafe query/repo, symbol not found, go unavailable). With root-resolution rules and prerequisites covered, only the opaque safety phrasing leaves a small gap.

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 each parameter (root, intention, session_id) already carries a detailed description, including an alias note for cwd. The description adds only the shape of the `query` value via the `go doc <query>` framing, so the schema is doing the heavy lifting and the baseline of 3 applies.

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

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

States a concrete verb and resource ('Fetch Go documentation ... by running `go doc <query>`') and enumerates the three query scopes (package, stdlib symbol, third-party symbol). It also explicitly separates itself from gograph_source and gograph_context, so the agent can route without opening sibling schemas.

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

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

Provides labeled WHEN TO USE ('When a call chain reaches code outside the project') and NOT TO USE ('For project-internal symbols') sections that name the exact alternative tools. This is the strongest part of the definition — the selection decision is fully determined.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only; no side effects" adds nothing. However, the description discloses non-obvious server behavior the annotations do not: freshness is checked and refreshed in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes, which explains otherwise puzzling latency or result shifts.

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

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

Front-loads the one-line purpose, then segments WHEN TO USE, NOT TO USE, and RETURNS, so each block is scannable. The freshness/CHA/SSA sentence is jargon-dense but conveys real behavior; the "Read-only; no side effects" clause duplicates annotations and is the only clearly wasted phrase.

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

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

With no output schema, the RETURNS block correctly takes on return-shape duty by naming parent struct names, package paths, and file locations, plus the empty-result contract. Minor gap: it does not say whether embedding is reported only for direct parents or followed transitively through nested embeddings, which matters for blast-radius use.

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 root, limit, cursor, struct, intention, and session_id are all documented in the input schema. The description adds no parameter-level meaning (e.g., exact-name matching vs qualified names, or how pagination interacts with embedding results), 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 ("Find all Go structs that embed the named struct via anonymous field composition") and immediately narrows the mechanism to anonymous field composition, which separates it from field-reference and interface queries. An agent can distinguish it from gograph_implementers and gograph_usages without opening either schema.

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

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

Explicit WHEN TO USE covers both exploratory (understanding how a base type is extended) and pre-mutation (blast radius before modifying a shared struct) cases. The NOT TO USE block names the correct alternatives by tool name and the exact condition that selects each.

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

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

The description adds real context beyond the annotations: a content-digest freshness check, incremental AST refresh, and a repository-wide CHA/SSA retry path after source changes, plus the caveat that dynamically computed prefixes remain unresolved. These are meaningful operational traits that annotations (readOnly/idempotent) do not convey. However, the freshness/retry paragraph is dense, partially opaque, and never says whether the call can be slow or how it behaves when analysis is refused, so the disclosure is informative but uneven.

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

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

Front-loaded correctly: capability first, then prefix-resolution behavior, then WHEN/NOT TO USE, then RETURNS, then parameter notes. Information density is high, though the freshness/CHA-SSA sentence is a long embedded clause that a reader may need twice. Slight trimming would improve it without losing content.

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

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

For a seven-parameter analytical tool with no output schema, the description supplies the missing return contract (array of slices with route/handler/chain/SQL/env fields, plus the found:false suggestion), coverage of query forms and depth semantics, and the freshness/fallback behavior. An agent has enough to call it correctly on the first attempt.

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 seven parameters, and the description mostly restates them (query forms, depth default 5). It does add one genuinely useful nuance not spelled out in the schema — that unresolved dynamic prefixes can still be reached via suffix or handler — but it never mentions root, mermaid, include_tests, intention, or session_id, leaving that to the schema. 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?

Opens with a specific verb and scope: 'Build a full vertical slice for one HTTP route', then enumerates the exact components of the slice (handler symbol, BFS call chain, SQL queries, env vars). It is immediately distinguishable from gograph_routes (list all routes) and gograph_source (raw handler code), which are named explicitly.

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?

Contains explicit WHEN TO USE ('auditing what an API endpoint does end-to-end') and NOT TO USE clauses that route the agent to two named siblings, gograph_routes for discovery and gograph_source for raw code. There is also a sequencing hint ('use gograph_routes first to find the pattern').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so "Read-only; no side effects" is largely redundant. However, the description adds genuinely non-obvious behavior: the server checks freshness before the call, refreshes in the requested analysis mode, and retries CHA/SSA for precise and precise_fallback graphs after source changes. That freshness/retry detail is the kind of context annotations cannot carry.

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

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

Front-loaded with purpose, then structured WHEN TO USE / NOT TO USE / RETURNS blocks, so an agent can scan quickly. The freshness sentence ("precise and precise_fallback graphs retry CHA/SSA after source changes") is dense internal terminology that costs a little more than it returns for callers who only need to know results are current.

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?

Six optional parameters are fully documented in the schema, and with no output schema the description supplies a RETURNS block covering key names, calling function, file/line, and the empty-result case. Combined with the freshness note and the static-analysis caveat, 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 baseline is 3. The description only restates the `term` substring filter with an example that already appears verbatim in the schema for `term`, and says nothing about `root`, `limit`, `cursor`, `session_id`, or `intention`, leaving the schema to do all parameter work.

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

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

The first sentence states a specific verb and resource ("Find all environment variable reads") and names the concrete detection surfaces (os.Getenv, os.LookupEnv, config frameworks) plus the enclosing-function context. It is clearly distinguishable from siblings such as gograph_sql and gograph_strings, which scan other artifact types.

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?

There is an explicit WHEN TO USE block (deployment config manifests, required env var documentation, secret-read auditing at startup) and an explicit NOT TO USE block that routes runtime-value needs and database queries elsewhere, naming gograph_sql directly. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations it discloses non-obvious behavior: a freshness check with refresh in the requested analysis mode, CHA/SSA retry after source changes in precise/precise_fallback graphs, and the heuristic caveat that no SSA or full data-flow tracking is performed. The 'read-only; no side effects' line repeats the annotations, but the added operational detail far outweighs that redundancy.

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

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

Front-loaded with the core action, then cleanly sectioned into WHEN TO USE, NOT TO USE, and RETURNS. Dense and largely earning its space, though the retry/analysis-mode sentence is heavy for a read tool and the side-effects line duplicates annotations.

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

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

With no output schema, the description fully covers returns: definition sites, return sites, propagation path chains, related test names, and the empty-paths case. It also flags the analysis-fidelity limit, so an agent knows what the result can and cannot prove.

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 parameter meaning is already documented. The description adds only the query-over-term preference, which is a useful but narrow increment over the schema's own '(preferred over term)' note. Baseline 3 applies when the schema carries the parameter burden.

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 (trace) and resource (a named error sentinel or message string) with scope: definition sites, return sites, and upward propagation to HTTP/CLI entry points. It names the sibling tools it is not (gograph_callers, gograph_impact, gograph_errors), so an agent can distinguish it 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?

Explicit WHEN TO USE section frames the end-to-end error audit use case with a concrete example (ErrNotFound), and NOT TO USE names the exact alternatives for general upstream traversal and for listing all errors. Both the use and the exclusion conditions are spelled out.

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

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

The annotations already declare readOnly/idempotent/non-destructive, so 'Read-only; no side effects' earns no credit, but the description adds genuinely new behavior: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. That tells the agent results reflect post-change source and explains latency/retry characteristics not visible in structured fields.

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

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

Front-loaded with the core purpose, then cleanly sectioned into behavior, WHEN TO USE, NOT TO USE, and RETURNS. Slightly redundant in repeating the annotations' read-only/non-destructive guarantee, but overall dense and well organized.

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

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

With seven parameters and no output schema, the description compensates by supplying a RETURNS section (message text, file path, line number, empty when no matches) plus freshness/refresh semantics. That is everything an agent needs to call it and interpret results correctly.

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

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

Schema description coverage is 100%, so root, limit, cursor, no_tests, intention, and session_id are already fully documented. The description only restates the optional `term` substring filter with the same examples the schema gives, adding no new meaning. Baseline 3 is correct when the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Find all error and panic sites') and enumerates exactly what counts as a site: errors.New, fmt.Errorf, sentinel var declarations, and panic calls. It also names the sibling it is not (gograph_errorflow), so an agent can discriminate without opening another schema.

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

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

Explicit WHEN TO USE lists three concrete scenarios (cataloging error codes and panic paths, standardizing messages, checking whether a string already exists) and an explicit NOT TO USE that routes propagation tracing to gograph_errorflow. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), yet the description adds genuinely new behavior: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. It also discloses the {"found":false} failure shape for symbols absent from the graph. Slightly more on what refresh means for latency/consistency would push this higher.

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 purpose followed by clearly labeled WHEN TO USE, NOT TO USE, and RETURNS blocks makes it easy to scan. The opening enumeration of ten content categories is long but each item conveys real scope, so little is wasted; the freshness/CHA-SSA sentence is the densest part.

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 read-only aggregate tool with no output schema, the description supplies everything an agent needs: what is produced, when to choose it over siblings, freshness/refresh semantics, and the not-found return case. No significant gap remains.

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

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

Schema description coverage is 100%, so all four parameters (root, symbol, intention, session_id) are already well documented in the schema. The description adds no additional meaning about symbol formats, root scoping, or session selection, so the baseline of 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 description opens with a specific verb and resource ("Generate a synthesized, LLM-ready narrative for a Go symbol") and enumerates exactly what the document contains (role, callers, callees, complexity, SQL, env vars, HTTP routes, concurrency, tests, interface satisfaction). This makes it clearly distinguishable from single-aspect siblings like gograph_callers or gograph_complexity: this is the aggregate view.

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

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

Explicit WHEN TO USE section names three concrete scenarios (onboarding, PR documentation, architectural assessment without multiple calls) and a NOT TO USE section routes to two named alternatives with their conditions (gograph_source for raw source, gograph_impact for targeted blast-radius). Nothing is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered; the description's 'Read-only; no persistent side effects' largely repeats it. It does add genuine behavioral context beyond annotations — the server refreshes source analysis before the call, question-like text is treated lexically rather than model-interpreted, and possible dispatch is excluded from bundled identity impact and deep traversals. That is useful, but the return-format sentence overlaps with what a RETURNS line normally covers and there is no output schema to anchor it.

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

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

It is front-loaded with the core action, then modes, then constraints, then a clearly labeled RETURNS clause, so an agent can stop reading early. It is dense with clauses ('Possible dispatch is excluded from bundled identity impact and deep traversals' is a mouthful), but almost every sentence carries distinct information rather than padding.

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

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

For an eight-parameter fan-out tool with no output schema, the description supplies the mode matrix, default limits, interaction rules, freshness behavior, and a RETURNS line naming the shared gograph.explore.v1 payload with totals and omission metadata. Nothing an agent needs to invoke it correctly — or to interpret what comes back — appears to be missing.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters, and the description's per-parameter restatements (compact, deep, limit defaults) mostly duplicate it. The one thing it contributes beyond the schema is the interaction rule that an explicit limit overrides the mode defaults, which the schema only implies. Baseline 3 is appropriate when the schema carries the weight.

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

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

The opening sentence gives a specific verb and resource ('Explore a lexical term or Go symbol') plus a bounding constraint ('one bounded call'), and the body enumerates exactly what the bundle contains (ranked matches, source, callers/callees, tests, impact). It does not name the sibling tools it overlaps with, only gesturing at 'focused tools remain authoritative', so an agent cannot map it to gograph_callers/gograph_impact/gograph_source by name.

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?

Mode selection is spelled out clearly: compact for low-token discovery, deep for expanded evidence, standard as the implied middle, with mutual exclusivity and limit-override rules stated. What is missing is explicit routing advice such as 'use gograph_callers instead when you only need callers' — the phrase 'Focused tools remain authoritative for complete output' hints at alternatives without identifying any.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description still adds real value: it discloses that the server checks freshness before the call, refreshes in the requested analysis mode, and retries CHA/SSA on precise graphs after source changes. It also states the empty-result condition when the struct is not found. What it omits is how the freshness latency or staleness window manifests to the caller, so it stops short of the top mark.

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 clearly labeled WHEN TO USE, NOT TO USE, and RETURNS blocks, so an agent can scan it quickly. The freshness/CHA-SSA sentence is dense jargon packed into the second sentence and could be trimmed, but no section is filler.

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

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

With no output schema, the RETURNS section correctly supplies the return shape and the empty-result sentinel, which is what an agent most needs. The one gap is that pagination is unmentioned in the description even though limit and cursor exist, so a caller with a large struct must infer paging 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 coverage is 100%, so root, limit, cursor, struct, intention, and session_id are all already self-documenting. The description names the target ('named Go struct') but adds no format or resolution rules for the struct identifier beyond what the schema states ('exact name ... e.g., Config, User'). Baseline 3 applies when the schema carries the semantics.

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 ('Extract all declared fields from a named Go struct') and enumerates exactly what comes back: field names, Go types, and raw tag strings. An agent can distinguish this from sibling introspection tools without opening the schema.

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

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

Explicit WHEN TO USE cases (tag mapping, layout inspection, pre-add enumeration) and explicit NOT TO USE routing to named siblings: gograph_node/gograph_source for methods and gograph_literals for initialization sites. Both the positive and negative cases are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real context: freshness checking before the call, mode-specific refresh with CHA/SSA retry after source changes, and that an empty result means the package has no test helper infrastructure. It does not address pagination behavior under the byte budget or how helper symbols are classified, which keeps it from a 5.

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

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

Front-loaded with purpose, then clearly labeled WHEN TO USE / NOT TO USE / RETURNS blocks that scan well. The sentence about freshness refresh and CHA/SSA retry is server-internal detail that adds length without influencing tool choice, so it is not perfectly economical.

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

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

There is no output schema, so the RETURNS section carries the return-value burden, describing what symbols come back and the empty-case meaning. Combined with the freshness note and the explicit exclusions, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so package, root, limit, cursor, session_id and intention are all documented in the schema. The description adds no syntax, format, or filtering semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Find test helper structs and factory/builder functions declared in *_test.go files for a named package' — narrowing scope to helper infrastructure rather than all test code. It explicitly contrasts with gograph_tests (test functions) and points to filesystem search for external test data, so an agent can separate it from the nearest siblings.

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?

Contains explicit WHEN TO USE (before writing new tests, to avoid duplicating existing builders/factories/setup structs) and NOT TO USE clauses that name the alternative tool for each excluded case. Nothing about selection is left to inference.

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

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

Annotations already declare read-only, idempotent, no side effects, but the description goes well beyond them: it discloses that the server refreshes source analysis before the call, that the analysis is path-insensitive, that call/return context defaults to 3 frames (max 16) with deeper returns degrading to low confidence, and that a size-derived work budget can return an explicitly incomplete run. That is substantive operational context an agent cannot get from annotations.

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

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

Front-loaded with purpose, then clearly labeled WHEN TO USE / NOT TO USE / RETURNS blocks. The NOT TO USE sentence is dense and packs several caveats (path-insensitivity, context depth, work budget) into one long construction, which slightly hurts scannability but every clause carries information.

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

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

For a 10-parameter analytical tool with no output schema, the description covers what it does, prerequisites, explicit limitations, what the findings contain (source, sink, severity, confidence, path steps), and how to configure sanitizers. An agent has everything needed to decide and 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 description coverage is 100%, so the schema already carries parameter meaning. The description nonetheless adds value by explaining that trusted return-value sanitizers are configured via .gograph/flow.json or the config parameter, and by naming the confidence/completeness consequences of the context_depth and max_work settings, which the schema states only briefly.

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 ('Find potential untrusted-data paths') and enumerates both source kinds (HTTP request objects, decoded JSON, environment variables) and sink kinds (SQL text, process execution args, filesystem paths, outbound HTTP). This is a specific taint-flow analysis, clearly distinguishable from a generic path or trace 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 has explicit WHEN TO USE ('during a security review or before changing request parsing, command execution, file access, SQL construction, or URL handling') and NOT TO USE sections, plus a stated prerequisite to run `gograph build . --precise` first. Alternatives aren't named by sibling, but the exclusion criteria do the routing work.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the server checks freshness and refreshes in the requested analysis mode, precise/precise_fallback graphs retry CHA/SSA after source changes, and the result is empty when the package is not found. It stops short of explaining pagination/limit/cursor behavior, which keeps it from a 5.

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

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

Front-loaded with the core action, then cleanly sectioned into WHEN TO USE, NOT TO USE, and RETURNS. The freshness/CHA-SSA sentence is dense but carries real information; overall it is appropriately sized for a six-parameter tool with no output schema.

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

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

For a tool with no output schema, the RETURNS section compensates by describing the shape of the result and the empty-package case. Pagination and session/intention semantics are left entirely to the schema, which is a minor gap given the schema's thoroughness.

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 every parameter including root, limit, cursor, package, intention, and session_id is already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Extract a comprehensive structural summary of one Go package') and enumerates exactly what is returned: files, defined symbols, internal call edges, and package-level imports. It also names the sibling tools it is not (gograph_context, gograph_source, gograph_query), so an agent can distinguish it without opening any schema.

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

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

Explicit WHEN TO USE ('orienting to an unfamiliar package before editing it') and NOT TO USE clauses that route to specific alternatives for single-symbol detail and global keyword search. Both the positive trigger and the exclusions are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-open-world, and the description reinforces 'Read-only; no side effects' without contradicting them. It adds genuine behavior beyond annotations: pre-call freshness checking, graph-mode refresh, and CHA/SSA retry after source changes. The CHA/SSA sentence is implementation jargon that adds less selection value than the rest, keeping it just short of a 5.

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

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

Purpose is front-loaded, and the WHEN/NOT/RETURNS structure is easy to scan. The freshness/CHA/SSA sentence is dense, jargon-heavy, and the least actionable part of the definition, adding mild bloat to an otherwise tight description.

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

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

Despite no output schema, the RETURNS section specifies variable names, types, mutating functions, and the empty-result case. With six parameters (one required) and pagination already documented in the schema, plus freshness behavior disclosed, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so root, limit, cursor, package, intention, and session_id are already fully documented in the schema. The description only implies the 'package' scoping; it adds no syntax, path-format, or pagination guidance beyond what the schema provides, which is the expected 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?

Opens with a specific verb+resource: 'Find package-level variable declarations (var blocks) and the functions that mutate them in a specific package.' This is clearly distinguishable from the many sibling graph tools (e.g., gograph_envs, gograph_fields, gograph_usages) because it names both the declaration kind and the mutation-tracking output.

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

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

Provides explicit WHEN TO USE scenarios (auditing mutable global state, thread-safety hazards, singletons before a concurrency refactor) and an explicit NOT TO USE clause that routes local-scope questions away and env variable reads to gograph_envs by name.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and 'Read-only; no side effects' merely restates them. However the description adds genuine behavioral context beyond annotations: a freshness check with automatic refresh, CHA/SSA retry on precise graphs after source changes, and the qualification/ranking rule (any exceeded threshold qualifies, combined excess ranks). That is meaningful for interpreting and trusting results.

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

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

Front-loaded with purpose, then labeled WHEN TO USE / NOT TO USE / RETURNS sections that are easy to scan. The freshness/refresh sentence is dense and slightly verbose, but overall every part contributes.

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 7 optional parameters and no output schema, the description supplies the missing return-value information via RETURNS (ranked candidates with method/field/call counts, empty when nothing exceeds thresholds). Nothing needed to call it correctly appears to be 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 each parameter is already documented in the schema. The description adds real value about how thresholds interact (any enabled threshold qualifies, combined excess determines rank) but otherwise repeats the defaults already in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Names a specific verb and target ('Detect God Object anti-pattern candidates') and states the scoring dimensions: method count, field count, outgoing call count. It also names the sibling tools it is NOT (gograph_fields, gograph_complexity), so an agent can disambiguate without opening other 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?

Explicit WHEN TO USE ('during architecture reviews to find monolithic structs that should be decomposed') and NOT TO USE with two named alternatives and the conditions that select them. Little is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, yet the description still adds real value: it discloses that the server checks freshness and refreshes in the requested analysis mode, and that precise/precise_fallback graphs retry CHA/SSA after source changes. The CHA/SSA phrasing is jargon-heavy and stops short of stating latency or staleness consequences, so it falls just short of a 5.

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

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

Front-loaded with the core ranking statement and organized into WHEN TO USE / NOT TO USE / RETURNS blocks that are easy to scan. The freshness/CHA-SSA sentence interrupts the flow with implementation detail an agent rarely needs when choosing the tool, slightly diluting an otherwise tight definition.

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?

Though there is no output schema, the RETURNS line specifies the shape ('ranked list of function names with fan-in count and package location'), which is exactly what the missing output schema would have covered. Combined with the exclusion of test-file edges and the configurable result count, 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 top, root, intention and session_id are already documented in the schema; the description largely restates the `top` default and the include_tests behavior that the schema already carries. It adds no new meaning for root, intention or session_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rank functions by incoming call count (fan-in)') plus the analytic intent ('identify the most-depended-on symbols'). The NOT TO USE clause explicitly names gograph_focus, gograph_coupling and gograph_complexity as the tools for adjacent questions, so an agent can disambiguate 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?

Provides an explicit WHEN TO USE ('deciding where to invest refactoring effort or documentation') tied to the semantics of high fan-in, and an explicit NOT TO USE routed to named alternatives. Both the positive and negative selection conditions are spelled out rather than implied.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds real operational context on top: the server refreshes source analysis before the call, runtime environment values are never read, and construction is not dispatch proof. It also discloses that unresolved destinations surface as workspace diagnostics and that workspace http_clients mappings can resolve bases or env:KEY, which are 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?

The scope statement is front-loaded and every sentence carries information about inference limits, resolution behavior, or return shape. It is dense and jargon-heavy, which costs some readability, but there is no filler or repetition.

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 static-analysis tool with six optional parameters, pagination, and session plumbing, the description covers scope, exclusions, refresh behavior, and return fields (file/line, dynamic base/suffix evidence, total/returned/truncated/next_cursor). Session and intention semantics are left to the 100%-covered schema, so the remaining gap is minor.

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 six parameters, and the baseline is 3. The description's note that the optional term matches method, URL/base, or function largely restates the schema, and it adds only the framing of results as a bounded page, which mildly clarifies limit/cursor without new syntax detail.

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

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

The description names a specific verb and resource: a bounded page of HTTP evidence from imported, unshadowed net/http Get/Post/PostForm/Head calls plus possible NewRequest/NewRequestWithContext construction. It also states explicit scope limits (client receiver methods and arbitrary URL-building functions are not inferred) and points to gograph_routes for server-side routes, so it is distinguishable from siblings without opening a schema.

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

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

It provides a clear usage context (client-side outbound HTTP evidence) and one explicit alternative: 'For server routes use gograph_routes.' It also states what the tool will not infer, which implicitly tells the agent when to look elsewhere. It does not, however, route the agent away from other plausible siblings such as gograph_endpoint, gograph_api, or gograph_envs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantive context: the server refreshes the graph first, ambiguous short names return every candidate and are never silently resolved, and the exact durability rules for canonical IDs (survives line shifts and file moves within a package; breaks on package/module moves, receiver changes, renames). These are behavioral facts an agent cannot get from the annotations or schema.

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

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

Front-loaded with the core action, then the ID-stability rules, then labeled WHEN TO USE and RETURNS sections, which makes it scannable. It is dense throughout and the ID-durability enumeration is wordy, but no sentence is filler.

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

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

With no output schema, the description correctly supplies the return contract: gograph.identity.v1 JSON with status values exact, ambiguous, or not_found plus deterministic matches. Combined with the ambiguity policy and the root/package scoping notes, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains why the optional package qualifier exists (the uncommon in-package versus external foo_test ID collision) rather than just restating it. It also clarifies what forms the symbol parameter accepts (exact name, qualified spelling, canonical ID), reinforcing the schema text.

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

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

The description opens with a precise verb+resource: resolve a symbol spelling or canonical stable ID to a location-independent identity plus current source location. That is far more specific than most siblings and implies the difference from lookup-style tools like gograph_node or gograph_usages. It never names a sibling tool to contrast against, so it stops short of the top bar.

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?

An explicit 'WHEN TO USE' line gives two concrete triggers: before persisting cross-document references, and to re-resolve an existing stable ID. That is clear positive guidance with real context. There are no explicit when-not-to-use conditions or named alternatives (e.g., when to prefer gograph_node or gograph_source instead).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real value: a freshness check before the call, the exact-vs-possible evidence distinction with dotted Mermaid edges, comparison against HEAD including selected untracked Go files, refusal of deleted declarations, and the instruction to rebuild before traversing new symbols. The middle section is muddied by a garbled sentence beginning 'Review instead includes changes --git HEAD declaration evidence', which reads as leakage about a sibling tool and weakens otherwise strong disclosure.

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

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

The structure is strong and front-loaded — purpose, freshness, modes, when/when-not, returns, edge cases — and every early sentence earns its place. However the final third becomes a dense run-on of edge-case rules ('Traversal consumers refuse deleted declarations requiring historical caller evidence...') plus the garbled 'Review instead includes' sentence, which costs the reader more than it returns.

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

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

For a 10-parameter, zero-required tool with no output schema, the description covers the essentials: what comes back (transitive upstream symbols, a bounded native page including empty pages, Mermaid text), error conditions for incomplete comparisons and missing identities, and the freshness prerequisite. The only real gap is that session/intention parameters, which gate analytical calls, are left entirely to the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot express: the three modes are mutually exclusive entry points mapped to `symbol`, `uncommitted`, and `since`, and it clarifies that mermaid swaps the response shape entirely. It does not add anything for root, limit, cursor, session_id, or intention beyond what the schema already documents.

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

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

The opening sentence gives a specific verb and resource — 'Traverse the call graph backwards to find every symbol that transitively calls the target' — and immediately frames it as 'the full upstream blast radius of a change'. It explicitly distinguishes itself from the sibling gograph_callers by scoping that tool to 'direct one-hop callers only', so an agent can route correctly without opening either schema.

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

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

Dedicated 'WHEN TO USE' and 'NOT TO USE' blocks name both the triggering situation (before refactoring a core function) and the alternative tool (gograph_callers) with the condition that selects it. The three invocation modes (symbol, uncommitted=true, since) are enumerated, which covers the main decision points an agent faces.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavior: test-file AST implementations are merged with type-checked production results, freshness is checked and refreshed in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. This is genuine context an agent could not infer, though freshness details are server-level rather than tool-level and pagination-by-byte-budget is left to 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 purpose is front-loaded, followed by behavior, then WHEN/NOT/ RETURNS in clearly separable blocks, so an agent can stop reading early. The freshness/CHA-SSA sentences are the densest and least actionable part, costing a point against an otherwise tight structure.

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

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

There is no output schema, and the description compensates with a RETURNS block specifying implementing struct names with package paths and file locations plus the empty-result case. Combined with the test_only merge semantics and the inverse-tool pointer, an agent has everything needed to call this correctly for a 7-parameter analytical tool.

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

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

Schema description coverage is 100%, so the schema already documents root, limit, cursor, session_id, intention, and test_only. The description adds only a use-case gloss for test_only ('*_test.go files (mocks/stubs)'), which largely restates the schema's own 'test or mock files (replaces gograph_mocks)' wording, 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 first sentence gives a specific verb and resource — 'Find all concrete structs that implement a named Go interface' — and the description explicitly names the inverse tool (gograph_interfaces) and the unrelated sibling (gograph_fields), so an agent can separate it from neighbors without opening any schema.

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

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

It carries explicit WHEN TO USE scenarios (polymorphism tracing, DI points, mock discovery) and an explicit NOT TO USE clause routing to gograph_interfaces for the inverse direction and gograph_fields for fields. It also states the discriminating condition for test_only=true (mocks/stubs), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces 'Read-only; no side effects.' It adds genuinely new behavioral context beyond annotations: the server checks freshness and refreshes in the requested analysis mode, and precise graphs retry CHA/SSA after source changes. The CHA/SSA sentence is jargon-heavy and its practical implication for the caller is left implicit, which keeps this from a 5.

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

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

Front-loaded with the core action, then cleanly sectioned into WHEN TO USE, NOT TO USE, and RETURNS, which is easy for an agent to parse. The freshness/CHA/SSA sentence is the one piece of internal machinery jargon that could be trimmed or made actionable.

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?

Covers purpose, selection criteria, exclusions with named alternatives, and return shape (including the empty-result case) for a tool with no output schema. Combined with a fully documented schema, 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 every parameter (root, limit, cursor, package, intention, session_id) is already documented in the schema. The description reinforces that the package must be an exact import path but adds no syntax, format, or edge-case detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Find all files and packages ... that import a specific package by its exact import path.' It also scopes the direction of the edge (importers, not imports), which is exactly the distinction an agent needs against the sibling tools.

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

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

Provides explicit WHEN TO USE (isolating third-party library usage before removal/replacement, tracing internal package consumption) and NOT TO USE clauses that name the correct alternatives: gograph_deps for outgoing imports and gograph_dependents for reverse lookup by short name. This is the strongest form of routing guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, but the description contributes real behavior beyond them: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. It also sets expectations for the empty-result case, which an agent needs in order to interpret a null answer correctly rather than assuming failure.

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?

Well front-loaded: the core definition and inverse relationship come first, then WHEN/NOT WHEN, then RETURNS, with labeled sections that are easy to scan. Minor waste remains — 'Read-only; no side effects' repeats what readOnlyHint and destructiveHint=false already say, and the CHA/SSA retry detail is more machinery than an agent needs to choose and call the tool.

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

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

There is no output schema, so the description must describe return values, and it does: interface names, method signatures, file locations, and the empty-set case. Combined with full schema coverage for the six parameters and annotations covering the safety profile, an agent has everything needed to select and 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 description coverage is 100%, so root, limit, cursor, struct, intention, and session_id are all documented in the input schema itself. The description only restates that a struct name is the input, adding no new syntax, naming, or resolution rules beyond 'e.g. AuthService' already in the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ('find all Go interfaces satisfied by a named concrete struct') and immediately frames it as the inverse of gograph_implementers. The formal definition — every interface whose method set is a subset of the struct's methods — makes the semantics unambiguous and distinguishable from every sibling in a 60+ tool namespace.

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

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

Explicit WHEN TO USE section gives a concrete scenario (before refactoring a method, to see which contracts break) and an explicit NOT TO USE section routes the agent to gograph_implementers for the inverse query and to gograph_node/gograph_public for interface declarations. That is exactly the when/when-not/alternatives structure the top score requires.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds genuinely new behavioral context: the server performs a freshness check and refresh in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes, which explains possible latency and result consistency. The one redundant sentence is 'Read-only; no side effects,' which merely restates the annotations, but it does not undermine the added value.

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

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

The description is front-loaded with the core purpose, then cleanly divides into WHEN TO USE, NOT TO USE and RETURNS sections, making it easy to scan. It is somewhat longer than necessary — the freshness/CHA/SSA sentence is implementation detail that could be trimmed — but no section is padding.

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

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

Although no output schema exists, the RETURNS section describes exactly what comes back (file paths and line numbers, empty when the struct has no direct initialization sites), and pagination is handled by limit/cursor in the schema. Combined with explicit exclusions and freshness behavior, 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 baseline is 3; every parameter including root, limit, cursor, intention and session_id is already documented in the schema. The description only clarifies the meaning of 'struct' implicitly via 'named struct' and does not add format or scoping detail beyond what the schema states.

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

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

States a specific verb and resource — find every composite-literal initialization site for a named Go struct — and even paraphrases the syntax (Foo{...}) so the agent knows exactly what code pattern is matched. It explicitly contrasts itself with gograph_constructors, which handles factory functions, so the two siblings are distinguishable without opening either schema.

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

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

Provides an explicit WHEN TO USE scenario (before adding a required field, to scope migration blast radius) and an explicit NOT TO USE clause naming the alternatives for adjacent cases (gograph_envs or grep for magic values, gograph_constructors for factory functions). Both the positive and negative routing conditions are spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real value: it discloses that the server checks graph freshness before the call, refreshes in the requested analysis mode, and that precise/precise_fallback graphs retry CHA/SSA after source changes. That is meaningful non-obvious behavior an agent would otherwise not know. It stops short of 5 only because pagination/byte-budget behavior is left entirely to 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?

Well structured with explicit WHEN TO USE / NOT TO USE / RETURNS segments and the purpose front-loaded. The freshness-and-CHA/SSA sentence is dense and somewhat internal, but it still earns its place as behavioral disclosure; only minor trimming would improve it.

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

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

There is no output schema, but the RETURNS line describes what comes back (test-file struct names with file locations, empty when no mocks exist), which compensates. Combined with the explicit alternative routing and freshness disclosure, an agent has enough to call this correctly; only per-parameter usage nuance is absent.

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

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

Schema description coverage is 100%, so all six parameters are already documented in structured form, including root, limit, cursor, session_id and interface. The description adds no syntax or format detail beyond that (e.g., no guidance on interface naming, aliasing, or cursor reuse), so the baseline 3 applies.

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

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

States a specific verb (find), a precise resource scope (structs in *_test.go files), and the concept (test doubles, mocks, stubs) in one front-loaded sentence. It also pins its identity by declaring it equivalent to gograph_implementers with test_only=true, so an agent can distinguish it from the many sibling graph tools immediately.

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

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

Explicit WHEN TO USE (finding existing mocks before writing a new one) and NOT TO USE (production implementers → gograph_implementers without test_only; new code → prefer gograph_implementers with test_only=true). Both the alternative and the condition selecting it are named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Read-only; no side effects' is largely redundant. The description earns credit elsewhere: it discloses that a precise graph widens detection to ++/+=, pointer aliasing, atomic/sync/wrapper and channel mutations, and that analysis re-runs after source edits — genuine behavior an agent could not infer from annotations.

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

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

The WHEN TO USE / NOT TO USE / RETURNS structure is front-loaded and scannable, with no filler sentences. The single weak spot is the redundant 'Read-only; no side effects' phrase that repeats the annotation block, and the analysis-mode sentence is dense enough to need 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?

With six parameters, one required, and no output schema, the description carries the return-value burden and does so via the RETURNS line covering mutation locations and indirect mutator method names. Paging behavior and the root/session parameters are only handled in the schema, but nothing essential 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 the baseline is 3, but the description adds real meaning to the required 'field' parameter by documenting the qualified Type.Field form and explaining why it matters (excluding same-named fields on unrelated types). Pagination, root and session parameters are left entirely to the schema.

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

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

The first sentence states a specific verb ('Find') and resource ('struct-field and package-global mutation sites'), and the exclusions sharpen the boundary further (local-variable assignments are out of scope). The NOT TO USE clause names the two sibling tools it could be confused with, gograph_fields and gograph_literals, so an agent can disambiguate 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?

Explicit WHEN TO USE ('diagnosing state changes or auditing mutability') and NOT TO USE sections route the agent directly, and the alternatives are named rather than implied. The added note about the analysis mode and re-running after source edits tells the caller the condition under which results will change.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely non-obvious behavior: the server checks freshness and refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes, plus an empty result when the name is not found. These are real operational traits beyond the annotations, though the CHA/SSA retry sentence is terse enough to be somewhat opaque.

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

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

Front-loads the core purpose, then uses clear labeled sections (WHEN TO USE / NOT TO USE / RETURNS), which is easy for an agent to parse. Slightly verbose in the freshness/CHA-SSA sentence, but nothing 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?

For a read tool with a rich schema and no output schema, the description covers purpose, alternatives, behavioral caveats, and return shape, which is close to complete. It does not mention pagination behavior or next_cursor despite the schema exposing limit/cursor, a minor gap for an agent handling multi-page results.

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

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

Schema description coverage is 100%, so all six parameters — including root scoping, limit/cursor paging, intention, and session_id — are already documented in the schema. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Fetch AST metadata for a named symbol, package, or file") and enumerates the returned fields: kind, file path, line number, signature, doc comment, struct fields. It explicitly positions itself relative to siblings ("lighter than gograph_source for metadata-only lookups"), so an agent can discriminate it without opening another schema.

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

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

Contains explicit WHEN TO USE and NOT TO USE sections with named alternatives: gograph_source for full source, gograph_callers/gograph_callees for call relationships. The selection condition (metadata-only vs. source body) is spelled out rather than implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavior: full BFS reachability semantics, a freshness check performed before the call, and CHA/SSA retry on precise graphs after source changes. That retry/freshness disclosure is genuinely non-obvious and not derivable from structured fields; the only weak spot is the redundant 'Read-only; no side effects' clause.

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

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

Front-loaded with the core definition, then cleanly partitioned into WHEN TO USE / NOT TO USE / RETURNS blocks. Dense but every sentence carries signal except the 'Read-only; no side effects' restatement of annotations.

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

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

With no output schema, the description compensates by describing the return payload (orphan symbols with package paths and file locations) and the empty-result meaning. Root semantics, freshness behavior, and pagination-via-schema together leave nothing an agent needs 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 root, limit, cursor, intention, and session_id are already fully explained in the schema, including the alias and page-budget caveat. The description adds nothing parameter-specific, which is acceptable at this coverage level but earns only the 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?

States a specific verb and resource ('Find functions and methods unreachable from...') and then enumerates exactly which roots count — main/init, test/benchmark/fuzz, HTTP route handlers, externally callable exports — plus the internal/ exclusion. That precision lets an agent distinguish it from gograph_usages and gograph_callers without opening any schema.

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

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

Explicit WHEN TO USE ('code cleanup or dead-code audits') and NOT TO USE ('checking one symbol's usages') with the two named alternatives. Both the positive condition and the exclusion are stated, which is the top of the scale.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description's "Read-only; no side effects" is redundant. The genuinely additive parts are the path-ranking rules, the deterministic tie-breaker, and the note that the server refreshes source analysis before the call, which is useful freshness context not available in annotations.

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

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

Front-loads the core action, then uses labeled WHEN TO USE / NOT TO USE / RETURNS sections that are easy to scan. The ranking-criteria sentence is dense but each clause conveys a real ordering rule; slightly more compact phrasing would earn a 5.

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

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

With six parameters, no output schema, and full annotation coverage, the description covers purpose, routing, ranking semantics, refresh behavior, and return shape (from, to, found, steps[], mermaid variant). Nothing material is missing 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 all six parameters including root, session_id, and intention are already documented in the schema. The description adds only the mermaid=true output mode, which the schema already states. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ("Find the best call chain from one symbol to another") and immediately contrasts it with the sibling gograph_impact in the NOT TO USE clause. An agent can distinguish this from impact/callers/callees analysis 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?

Has explicit WHEN TO USE ("confirm reachability between non-adjacent symbols") and NOT TO USE ("all transitive upstream callers — use gograph_impact") sections naming the alternative tool. This is the strongest form of routing guidance.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real behavioral context on top: the server checks and refreshes graph freshness before the call, precise modes retry CHA/SSA after source changes, uncommitted modes compare against HEAD including untracked Go files, and traversal consumers refuse deleted declarations. The later sentences about review/incomplete comparisons are dense and somewhat ambiguous, which keeps it from a 5.

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

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

Purpose and the WHEN/NOT TO USE routing are well front-loaded, but the middle and tail are crowded with mode-specific prose ('Traversal consumers refuse deleted declarations...', 'Review instead includes changes --git HEAD declaration evidence...') that is hard to parse and partly duplicates sibling-tool description territory.

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

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

With no output schema, the description carries the return shape itself and does so concretely (inspect_first[], tests[], routes[], env[], risk object, optional inspect_contexts[]). It also covers error conditions and mode semantics; the remaining gap is that root/session prerequisites are documented only in the schema, not the description.

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