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

Even with annotations declaring readOnly, idempotent, and non-destructive, the description adds critical behavioral details: it extracts a temporary archive removed after the call, checks freshness, refreshes in the current analysis mode, and retries CHA/SSA for precise graphs. These details go far beyond the annotations and clarify the tool's runtime behavior.

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

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

The description is structured with clear sections (intro, parameter behavior, safety, WHEN/NOT TO USE, RETURNS). Every sentence carries specific information, and the most important facts are front-loaded. It's longer than most but each sentence earns its place, making it efficient and scannable.

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

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

With one parameter, no output schema, but supported by rich annotations, the description covers all necessary aspects: input semantics, execution behavior (including failure modes and side effects), return structure, and intended use cases. It leaves no significant gaps for an agent to invoke the tool correctly.

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

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

The schema covers 100% of the single parameter 'since', but the description enriches it with significant semantics: it explains the two accepted value types (Git ref vs .json saved graph), special handling for .json paths, and the meaning of 'regular saved graph' with source-policy marker. This adds value beyond the schema's basic description.

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 statement: 'Detect public API surface drift by comparing exported Go symbols between the current working tree and a baseline.' It clearly distinguishes itself from sibling tools like gograph_public and gograph_skeleton by explicitly stating it's for diffing against a baseline, not listing current exports.

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?

WHEN TO USE and NOT TO USE sections are explicit and actionable. It says use before releasing or merging a PR to catch breaking changes, and directs users to gograph_public or gograph_skeleton for listing current exports without a baseline. This is the gold standard for usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only; no side effects.' It adds useful context beyond annotations by mentioning the MCP server checks freshness before the call, which is a behavioral trait not captured 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?

The description is compact, uses clear section headers (WHEN TO USE, NOT TO USE, RETURNS), and every sentence adds meaningful information. It is well-organized and front-loaded with the core purpose.

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 simple tool with one optional parameter and no output schema, the description is complete: it explains what it returns (parameter count, signature, file location), covers usage scenarios, and indicates the freshness check. No critical information 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% for the single 'min' parameter, so the schema already documents it well. The description adds value by explaining the default and edge case (0 includes zero-arity functions) and mentioning the CLI --min equivalence, which provides additional context 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 description clearly states a specific action ('Find') targeting a specific resource ('functions and methods') with a clear qualifier ('at least a threshold number of parameters') and explicitly names the code smell it addresses ('long-parameter-list smell'). It also distinguishes itself from sibling tools by mentioning alternatives 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?

The description provides explicit WHEN TO USE and NOT TO USE sections, including concrete alternative tool names (gograph_fields, gograph_godobj). This gives the agent clear guidance for tool selection and exclusion criteria.

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 and closed-world, so safety is covered. The description still adds real context beyond them: it refreshes source analysis, enforces that config paths stay inside the analyzed project, and reads every path component through the rooted repository boundary. It stops short of noting cost/pagination behavior of the refresh.

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 WHEN/NOT/RETURNS blocks that are easy to scan. The middle clause about path components and the rooted boundary is dense and slightly redundant with the config param description, holding it below 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?

Even with no output schema, the RETURNS line tells the agent to expect structured pass state and boundary violations, and the WHEN/NOT guidance plus config prerequisites make the tool fully callable. 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 the baseline is 3, but the description adds meaning the schema lacks – the config path must be in-project, non-linked, and defaults to .gograph/boundaries.json. It adds a bit of the boundary-safety constraint rather than merely restating field descriptions.

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

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

States a specific verb (check) plus resource (package imports against a boundaries config) and immediately differentiates from siblings by naming gograph_deps and gograph_coupling as the tools for unconstrained exploration. An agent can pick this tool 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 (CI gates, post-edit reviews for layer separation) and NOT TO USE (dependency exploration) sections, with the alternative siblings named by tool. Also points to gograph_boundaries_create for creating the required config, covering the setup path.

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 indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds meaningful context: 'Mutating and non-idempotent; no network access', and explicitly states safety behaviors like refusing linked paths and overwriting. This goes beyond the annotations and provides operational constraints.

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-structured with a clear purpose statement, followed by behavior details, THEN/NOT TO USE, and RETURNS. It is slightly longer than a minimal description but every sentence adds value, avoiding 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?

For a single-parameter create tool with no output schema, the description is comprehensive: it covers what it does, when to use it, safety constraints, and the return value ('The written config path or an error when the path is unsafe or already exists'). No critical gaps remain.

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 parameter is already well-documented. The description adds the default path value ('.gograph/boundaries.json') which is not in the schema description, but this is a minor addition. The baseline of 3 applies since the schema does the heavy lifting.

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

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

The description clearly identifies the action ('Create a baseline architecture boundary configuration') and the resource ('from the repository's current package imports'). It also distinguishes from the sibling tool gograph_boundaries by specifying NOT TO USE for verification, making it highly distinguishable.

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

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

The description provides explicit 'WHEN TO USE' (once when adopting boundary checks) and 'NOT TO USE' (to verify an existing configuration, with the alternative gograph_boundaries named). This is exemplary guidance that directly addresses tool selection.

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 safety is covered; the description nonetheless adds genuinely new behavioral context, namely that the MCP server refreshes source analysis before the call and that depth 2-10 expands the traversal. It stops short of latency/cost implications of that refresh, so not quite 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 and defaults, then cleanly sectioned into WHEN/NOT TO USE and RETURNS. Dense but every sentence carries distinct information; 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?

With no output schema, the RETURNS section correctly carries the return-shape burden (callee symbols, package paths, file locations, call-site line numbers, Mermaid text) and the refresh behavior is disclosed. An agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the default fan-out and the depth 2-10 expansion semantics, and by naming the mermaid=true alternate response mode. It adds meaning beyond the schema rather than restating it.

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

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

States a specific verb+resource ('Find functions and methods called by the specified function') and immediately scopes it against sibling tools by name ('use gograph_callers', 'use gograph_deps'). An agent can select it correctly 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 and NOT TO USE sections that name the two most confusable alternatives and the exact condition that routes to each (upstream callers vs. package dependency trees). This is the strongest possible guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered; the description's 'Read-only; no persistent side effects' partly duplicates that. It adds genuine non-obvious behavior beyond the annotations: the server refreshes source analysis before the call, the default is one-hop fan-in with depth 2-10 expanding callers-of-callers, and interface method calls expand through implementations but report a shared source call site once.

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 action leads, then scope/defaults, then WHEN TO USE / NOT TO USE / RETURNS blocks. Dense but each block carries distinct information; only the 'Read-only; no persistent side effects' clause is somewhat redundant with 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?

No output schema exists, so the RETURNS block (caller symbols with package paths, file locations, call-site line numbers, and Mermaid text) is necessary and present. Combined with pagination notes implied by cursor/limit, the definition gives an agent 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 coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: it explains the depth semantic (default one-hop vs 2-10 expanding callers-of-callers), the mermaid=true output switch, and the interface/concrete dot-notation behavior behind the 'function' and 'exact' parameters. These are usage-level semantics not stated in the 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?

States a specific verb and resource ('Find functions and methods that call the specified function or interface method') and immediately differentiates from siblings by contrasting with gograph_impact (upstream blast radius) and gograph_callees (downstream). An agent can distinguish it from the ~60 sibling 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?

Contains explicit WHEN TO USE ('Before renaming, removing, or changing a function or interface method signature') and NOT TO USE clauses that name alternative tools (gograph_impact, gograph_callees) with the conditions that select each. 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, and destructiveHint=false, so much is covered. The description nonetheless adds real value by stating there is no graph-state prerequisite once the server has started and by describing the return payload, which annotations cannot convey.

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

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

Front-loaded purpose sentence, then labeled WHEN TO USE / NOT TO USE / RETURNS sections. Every sentence carries distinct information; 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?

With no parameters and no output schema, the description compensates by enumerating the return contents (version, tool names, purposes, workflow sequences, limitations). An agent knows exactly what it gets and when to invoke it.

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

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

The tool takes zero parameters, which is the baseline-4 case. The schema is empty and the description correctly implies a no-arg invocation, so no parameter clarification is needed or missing.

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

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

States a precise verb (List) and a clearly scoped set of resources: server version, all registered MCP tools, their purposes, and recommended workflows. This meta/self-description role is unmistakably distinct from every analytical sibling such as gograph_summary or gograph_stats.

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 ('call once per session to orient before issuing analytical queries') and NOT TO USE ('do not repeat after capabilities are cached'). Both the triggering condition and the anti-pattern 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 cover the read-only/idempotent safety profile, and the description layers rich additional context: behavior with vs without git_ref, that deselected files are excluded rather than deleted, that unsafe inputs/parse failures yield diagnostics and never deletion proof, and that missing legacy fingerprints resolve to 'unknown'. This is exactly the beyond-annotations behavioral detail the dimension rewards.

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 and uses clear WHEN/NOT/RETURNS sectioning, so structure is strong. However it is quite long and dense for a one-parameter tool, with some jargon-heavy clauses (native gograph.changes.v1, current-graph consumers) that could be trimmed.

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

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

There is no output schema, so the description carries the full return-value burden and discharges it well by enumerating the complete/partial/cannot_evaluate states, diagnostics, changed_files, and the symbol-row categories, plus CLI exit-code semantics. For a complex comparison tool this is thoroughly complete.

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 single git_ref parameter is already documented, establishing a baseline of 3. The description adds genuine meaning by explaining the semantic split between omitting git_ref (trusted persisted graph, no refresh) and supplying it (refresh and confined baseline extraction), which the schema alone does not convey.

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 lead sentence states a specific verb and resource: compare Go declaration fingerprints including bodies, with the key differentiator of not marking every symbol in an edited file as modified. It is distinguishable from siblings like gograph_stale and gograph_impact, though the opening clause is dense and takes a moment to parse.

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 to identify changed declarations before impact/review') and NOT TO USE ('For line-level diffs or a complete census when evaluation is partial/cannot_evaluate') sections route the agent precisely, and it names a concrete alternative workflow ('Inspect changes --git REF'). 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 annotations (readOnly/idempotent/no-destructive/no-open-world), the description discloses substantial behavior: config path confinement rules, how a `.json` baseline is validated vs. treated as a Git ref, what uncommitted mode compares against, and specific refusal conditions (incomplete comparisons, deleted declarations, missing/ambiguous graph identities). This is rich operational context the annotations cannot convey.

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

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

Front-loaded purpose with clearly labeled WHEN/NOT/RETURNS sections that aid scanning. It is dense (config path semantics and baseline validation are stated at near-schema level of detail and partially restated), but every section is purposeful and no sentence is pure filler.

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

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

With no output schema, the description supplies a RETURNS summary (pass/warn/fail status, findings, summary counts) and covers the tricky edge cases (incomplete comparisons, historical caller evidence, identity ambiguity) an agent must anticipate. Complete for a tool of this complexity.

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 already 100%, so the baseline is 3, but the description adds real meaning: it clarifies the marker/linked-component validation for `.json` baselines, that the serialized root is ignored, and that otherwise the value is extracted as a Git ref. That goes beyond the schema's terse parameter text.

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

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

States a specific verb+resource ('run static policy checks') and enumerates the exact check families covered (boundaries, API drift, route/export tests, coverage, orphans, globals, arity, complexity). An agent can tell this is a composite policy-check tool that bundles what the sibling single-topic tools (gograph_boundaries, gograph_coverage, etc.) expose individually.

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 PR review or pre-commit analysis' and 'NOT TO USE: For CI process exit enforcement (use CLI gograph gate)', giving both the trigger context and the named alternative. Nothing about when to select this over siblings 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 and non-destructive, but the description adds substantial behavior: UNKNOWN handling with score -1, freshness checks and retry logic in specific graph modes, and side-effect-free guarantee. This goes well beyond the structured 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 description is longer than the ideal two-sentence pattern but is well structured with labeled sections (WHEN TO USE, NOT TO USE, RETURNS). It remains readable and every sentence contributes useful 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?

Even without an output schema, the description covers return shape (list of functions with score and severity label), empty-result behavior, and edge cases (UNKNOWN functions). This is complete for a reporting tool with no nested objects.

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% for the only parameter `symbol`, so baseline is 3. The description merely restates that it is an optional substring filter, adding minimal semantic value 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 description opens with a specific verb+resource: 'Report estimated cyclomatic complexity for Go functions' and adds sorting and severity labels. It clearly distinguishes from sibling tools by naming alternatives like gograph_coupling and gograph_deps.

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 are present, with concrete alternatives for other metric types. This gives the agent unambiguous guidance on tool selection.

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 read-only/idempotent/no-destruction profile, and the description goes further by disclosing the server-side freshness check and refresh-in-current-mode behavior, plus the CHA/SSA retry on source changes. The 'Read-only; no side effects' clause merely restates annotations, and the 'RETURNS' details about file/line/kind are useful but expected.

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 resource set, then cleanly sectioned into WHEN TO USE / NOT TO USE / RETURNS. Slightly over-long due to the redundant 'Read-only; no side effects' line and a dense freshness/refresh sentence, but overall 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?

For a read-only discovery tool with no output schema, the description supplies the return shape (file locations, line numbers, primitive kind), the empty-result case, and the explicit exclusion of channel receives and select statements. Combined with annotations covering safety and the schema covering params, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents term, limit, and cursor. The description only adds example filter terms ('mutex', 'goroutine', 'channel'), which is marginal value over 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?

The description names a specific verb (Find) and enumerates the exact resource set: goroutine spawns, channel sends, and calls on sync.Mutex/RWMutex, WaitGroup, and Once. It further distinguishes itself from siblings by directing sequential-flow queries to gograph_callers/gograph_callees, so an agent can identify this tool 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 (race-safety audit, async flow understanding, locating synchronization points before a concurrency refactor) and NOT TO USE (sequential call flow, with named alternatives gograph_callers/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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds valuable context beyond that: the freshness check before the call, refresh in the current analysis mode, and CHA/SSA retry after source changes, plus the empty-result behavior. It does not, however, detail pagination/cursor interaction beyond what the schema states.

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

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

Front-loaded with the core definition and organized into labeled WHEN TO USE / NOT TO USE / RETURNS blocks that make scanning easy. The freshness/retry sentence is dense and somewhat implementation-flavored, but it still earns its place as behavioral context.

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

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

Although there is no output schema, the RETURNS section describes the return shape (constructor names with signatures, package paths, file locations; empty when none found). Combined with 100% schema coverage on inputs and the sibling routing, 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 limit, cursor, and struct are all fully documented in the schema. The description adds no syntax or format detail for the struct parameter beyond the schema's own example. 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?

States a specific verb and resource: 'Find all factory and constructor functions that instantiate and return a named Go struct,' with a parenthetical defining the exact return-type condition. It explicitly disambiguates from the closest siblings (gograph_literals, gograph_fields), so the agent can route correctly without opening schemas.

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

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

Provides explicit WHEN TO USE conditions (finding the canonical creation path, pre-modification impact checks) and NOT TO USE exclusions that name the correct alternative for each case (literals, fields). Nothing is left to inference about when this tool is the right pick.

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/idempotent/destructive/openWorld, and the description adds substantial context beyond them: the freshness-check-before-call behavior, precise/precise_fallback CHA/SSA retry semantics, the audit-session telemetry caveat, and the uncommitted-mode declaration-vs-HEAD comparison rules including refusal conditions. It also documents partial-failure behavior (source_error, graph_state.read_diagnostic) and named errors.

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 and clearly labeled WHEN TO USE / NOT TO USE / RETURNS sections make it scannable despite its length. The opening paragraph is dense with internals (CHA/SSA retry, precise_fallback) that are less relevant to selection, adding some weight without much routing value.

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

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

There is no output schema, so the description carries the full burden and meets it: it spells out the JSON return fields (node, nodes[], source, callers[], callees[], tests[], test_results[], role), the uncommitted contexts[] variant, error/partial-context states, and the git-inspection follow-up. For a tool with a batch mode and multiple failure paths, this is complete.

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 defines exact, symbol, and uncommitted, making the baseline 3. The description adds value by tying uncommitted=true to a different return shape (contexts[], count:0) and to declaration-census/HEAD comparison semantics, which goes slightly beyond the schema's own wording.

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

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

States a specific verb (fetch) and resource (pre-flight context bundle for a single Go symbol) and enumerates exactly what the bundle contains: AST node metadata, source, direct callers, direct callees, tests, and role classification. It distinguishes itself from siblings by explicitly naming gograph_focus and gograph_impact as the tools for adjacent needs, so an agent can route 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?

Includes explicit WHEN TO USE ('first call before editing a symbol — eliminates 4–5 separate tool roundtrips') and NOT TO USE clauses that name the alternatives and the conditions that select them (gograph_focus for package orientation, gograph_impact for transitive 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds 'Read-only; no side effects' which is consistent. It also discloses that the server refreshes source analysis before the call and mentions mermaid output behavior, providing extra behavioral context beyond 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?

The description is well-structured with labeled sections for WHEN TO USE and RETURNS, and it stays compact. It includes a small redundancy ('Read-only; no side effects' duplicates annotations) but overall every sentence contributes value.

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

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

There is no output schema, so the description compensates by stating that returns are 'Package coupling records' and that Mermaid flowchart text is returned when mermaid=true. The metrics are already explained in the first sentence, making the return type sufficiently clear, though more detail on record fields or sorting would improve completeness.

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 descriptive text for every parameter, so the baseline is 3. The description adds a brief restatement ('package filters by substring; include_stdlib and internal_only control scope') but does not meaningfully clarify parameter semantics beyond what the schema already provides.

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

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

The description opens with a specific verb ('Report') and precisely names the metrics: fan-in (Ca), fan-out (Ce), and instability I=Ce/(Ca+Ce) per package. This clearly distinguishes gograph_coupling from sibling tools like gograph_deps or gograph_imports, which focus on different aspects of dependencies.

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' section states 'To evaluate package isolation,' giving a clear and actionable use case. It does not name alternative tools or conditions when not to use it, so it falls short of the full explicit-exclusion bar.

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 and idempotentHint=true. The description goes well beyond that: it discloses that the server refreshes the graph first, explains how exact versus possible results are determined via static vs CHA/parser-only dispatch edges, and specifies ambiguity handling. It explicitly states 'Read-only; no side effects' and distinguishes static attribution from runtime or branch coverage, which is critical behavioral context for an AI agent.

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 structured and information-dense, using clear sections for when to use, not to use, and return value. Every sentence adds behavioral or semantic detail. It is longer than minimal, but the tool involves non-trivial precision semantics and ambiguity handling, so the length is justified. The most important statement about transitive reachability is front-loaded.

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

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

The description is complete for a read-only analysis tool with no output schema. It covers the core behavior, the degradation semantics, ambiguity resolution, retry strategies, exact-mode filtering, the optional package qualifier, and a summary of what the return payload contains. There are no obvious missing behavioral details an agent would need to invoke the tool correctly.

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

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

The input schema already has 100% description coverage for all three parameters. The tool description still adds meaningful semantic context: 'test' is clarified as exact name or canonical stable ID with guidance to use matched_tests/gograph_identity for retries; 'package' is defined as resolving the uncommon in-package versus external foo_test collision; 'exact_only' is connected to omitting possible results. This expands beyond the 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 opens with a specific verb-resource statement: 'Return the transitive set of production functions and methods statically reachable from one test function.' It clearly defines the input (a test function) and the output relationship, and it disambiguates from siblings like gograph_tests, gograph_untested, and gograph_callees by emphasizing static reachability from a single test rather than coverage claims or general call graphs.

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 explicitly provides WHEN TO USE ('map one test to the product symbols it structurally exercises') and NOT TO USE ('To claim execution or branch coverage') sections. It also gives concrete conditional guidance for ambiguous cases: same-named tests return status=ambiguous, and the agent should retry with the stable test ID from matched_tests or gograph_identity. The package qualifier is framed precisely as resolving only the in-package versus external foo_test collision.

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

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

Annotations already cover read-only/idempotent/no-destructive safety, so 'Read-only; no side effects' is largely redundant. However, the description adds genuine behavior beyond the annotations: the server refreshes source analysis before the call (freshness guarantee) and the mermaid return-format branch. This extra context is useful but modest.

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 WHEN TO USE / NOT TO USE / RETURNS. Every sentence earns its place with 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?

For a read-only query with no output schema, the description covers purpose, routing to alternatives, freshness behavior, and return format (including the mermaid variant). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit, cursor, mermaid, and package are all documented in the schema itself. The description only echoes the mermaid=true behavior and adds no syntax or format detail beyond what the schema already provides, so 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 all packages that import the named package') and distinguishes itself from siblings by naming gograph_deps as its inverse. An agent can tell exactly what this returns 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 ('Before a package-level interface change or removal') and NOT TO USE ('For a single function's callers (use gograph_callers)') with a named alternative. The condition selecting the sibling is fully 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read-only; no side effects' is redundant. However, it adds valuable context: the MCP server refreshes source analysis before the call, and it documents the 'found:false' return condition. This goes beyond 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 description is moderately long but highly structured: purpose, behavior, when to use, when not to use, and return format. Every sentence carries information. The capitalized labels (WHEN TO USE, NOT TO USE, RETURNS) improve scannability. A slight trim could be made, but it remains efficient.

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 and moderate complexity, the description fully explains behavior, settings, return values, and edge cases ('found:false'). It also addresses the refreshing behavior, making it self-contained. Sibling differentiation is present. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the default for transitive (false) and clarifies the return structure (direct[] vs transitive[]), which is not explicitly in the schema. This strengthens parameter understanding without being repetitive.

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: 'List the import dependencies of a named package.' It clearly distinguishes itself from sibling tools by explicitly naming gograph_dependents as the reverse lookup tool. The transitive flag and its effect on scope are also mentioned.

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 are provided. 'When auditing package layering' gives a concrete use case, and the exclusion of gograph_dependents for reverse lookup prevents misuse. This is exactly the kind of guidance needed.

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 and idempotent; the description reinforces this with 'Read-only; no side effects' and adds behavioral context: refreshing source analysis, returning Mermaid text, and advising max_depth/grouping for large graphs. This goes beyond 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?

The description is well-structured with labeled sections (WHEN TO USE, NOT TO USE, RETURNS), front-loads the purpose, and every sentence earns its place. It is concise while packing substantial 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?

Given annotations cover safety and schema covers parameters, the description provides complete operational context: output format (Mermaid text), typical use cases, exclusions, and scale guidance. Since no output schema exists, stating the return type is critical and handled.

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

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

Schema covers all three parameters fully, so baseline is 3. The description adds practical guidance for group_by values and max_depth for large graphs, enhancing meaning beyond schema. include_stdlib is not mentioned but the schema description is sufficient.

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

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

The description clearly states it generates a Mermaid architecture diagram of the package dependency graph, with a specific verb and resource. It also distinguishes from siblings by explicitly excluding call-graph traversal and single-package focus.

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 and NOT TO USE sections, plus parameter-specific guidance for monorepos (group_by=module) and drill-downs (group_by=file). This gives clear direction on when to select this tool over alternatives.

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

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

The description goes far beyond the annotations, detailing rejection of filesystem-shaped queries, refusal of certain source-tree links and Go metadata, validation of member directories/go.mod files, open-world dependency resolution, and return/error behavior. It fully discloses the safety and execution model without contradicting the read-only, idempotent, open-world hints.

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

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

The description is lengthy but purposefully structured with clear sections (WHEN TO USE, NOT TO USE, RETURNS) and front-loaded with the core action. Every sentence adds value, though the dense security preflight details could be more compact. It remains readable 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?

The description is complete for a tool of this complexity. It covers the return format (one-element JSON array with query and output), error conditions, prerequisites, and behavioral edge cases. With no output schema and only one parameter, the description adequately fills all gaps.

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

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

The schema already describes the query parameter with concrete examples, achieving 100% coverage. The description adds context about acceptable query types (package, stdlib, third-party) and restrictions (filesystem-shaped rejected), which is useful but not a significant departure from the schema. Thus 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?

The description opens with a specific verb and resource: 'Fetch Go documentation for a package, stdlib symbol, or third-party symbol by running `go doc <query>`.' It clearly distinguishes from siblings by noting the tool does not query the graph and by explicitly contrasting with gograph_source and gograph_context for project-internal symbols.

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 ('When a call chain reaches code outside the project') and NOT TO USE ('For project-internal symbols (use gograph_source or gograph_context)') sections, naming alternative tools. It also states prerequisites about the MCP server needing a usable artifact or buildable source, giving clear context for when the tool is applicable.

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, so 'Read-only; no side effects' is redundant. However the description adds genuinely useful disclosures beyond the annotations: the freshness check/refresh behavior before the call and the CHA/SSA retry on precise and precise_fallback graphs after source changes. These are real behavioral traits an agent cannot get 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-loads the purpose, then organizes WHEN/NOT/RETURNS into scannable labeled clauses. The freshness/CHA-SSA sentence is somewhat implementation-heavy for the value it adds, but the overall structure is tight and every other sentence earns its place.

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

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

Despite having no output schema, the description spells out the return shape (embedding parent struct names with package paths and file locations, empty when nowhere embedded), so an agent knows exactly what to expect. Together with usage guidance and freshness semantics, the definition is complete for a 3-param read-only query.

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 limit, cursor, and struct are all documented in the schema itself. The description only restates that a named struct is the target, adding no syntax or edge-case detail (e.g., exact-name matching, pagination semantics) beyond 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?

States a specific verb (Find) and resource (Go structs that embed the named struct via anonymous field composition), and explicitly distinguishes itself from gograph_implementers and gograph_usages. An agent can identify the tool's niche 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?

Has explicit WHEN TO USE ('understanding how a base type is extended', 'estimate blast radius before modifying a shared embedded struct') and NOT TO USE sections that name the two alternative tools for adjacent questions. 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?

The description adds transparency beyond the annotations by explaining internal behaviors such as content-digest freshness checks, incremental AST refreshes, and handling of dynamic prefixes. While valuable, some details are repeated, slightly reducing impact.

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 overly verbose and repetitive. It repeats parameter descriptions, route-resolution details, and the concept of depth multiple times. It could be streamlined to half its length without losing essential 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?

The description compensates for the lack of an output schema by describing the return structure (array of endpoint slices with route, handler, call chain, SQL, env fields) and the not-found case (found:false with suggestion). It also explains the refresh behavior, making it fairly complete.

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

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

The schema already provides descriptions for all four parameters, and the description repeats these almost verbatim. It adds minimal extra clarification (e.g., depth meaning, mermaid alternative) but does not significantly enhance understanding 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 description clearly states that the tool builds a full vertical slice for one HTTP route, listing the specific outputs (handler symbol, BFS call chain, SQL queries, env vars). It differentiates from sibling tools by focusing on a single route and its end-to-end behavior.

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 explicitly provides usage guidance via 'WHEN TO USE' and 'NOT TO USE' sections, naming alternatives like gograph_routes for listing all routes and gograph_source for raw source code. This gives clear direction on when to choose this tool over others.

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 context beyond the annotations: the freshness check before the call, mode-dependent CHA/SSA retry after source changes, and an empty-list return when no reads match. It restates 'read-only; no side effects' (redundant with annotations) but the freshness/retry disclosure is substantive.

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: purpose first, then behavior, then labeled WHEN TO USE / NOT TO USE / RETURNS sections. It runs somewhat long and the term example duplicates the schema, but every section maps to a decision the agent must make, so there is little waste.

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

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

With no output schema, the description carries the return-value burden and does so (key names, calling function, file/line, empty case). Combined with freshness/retry behavior and full parameter coverage, an agent has what it needs; only the limit/cursor pagination interplay is 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 description coverage is 100%, so all three parameters are documented in the schema itself (term with the DATABASE example, limit as rows-per-page with byte budget, cursor as opaque next_cursor). The description largely repeats the term example and adds no semantics for limit or cursor, so the baseline 3 for full schema coverage is correct.

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) and resource (environment variable reads) and enumerates the exact detection mechanisms (os.Getenv, os.LookupEnv, config frameworks) plus enclosing function context. An agent can distinguish this from siblings like gograph_globals or gograph_literals 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 (deployment manifest, documenting required env vars, auditing secrets) and NOT TO USE clauses, including a named alternative (gograph_sql for database queries) and the clarification that this is static, not runtime, analysis. Routing is unambiguous.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: freshness checks, retry of CHA/SSA after source changes, and that it's heuristic without full SSA or data-flow tracking. This exceeds annotation coverage.

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-structured with sections but slightly verbose. It front-loads the core purpose and clearly separates usage guidelines and return information. Efficient but could be more concise.

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 description specifies what is returned (definition sites, return sites, propagation paths, test names) and explains edge cases (paths empty when no chain). It also notes the heuristic limitation. Complete for a complex analysis tool.

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

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

Schema coverage is 100%, so baseline 3. The description adds nuance: 'query' is preferred over 'term', and explains the boolean 'no_tests' excludes test files. This provides helpful guidance beyond 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 clearly states the tool traces how a named error sentinel or string is defined, returned, and propagates up the call graph toward HTTP handlers or CLI entry points. It distinguishes from siblings by explicitly saying not for general upstream traversal (use gograph_callers or gograph_impact) and not for listing errors (use gograph_errors).

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 describes auditing a specific error end-to-end, and NOT TO USE section provides alternatives for general traversal and error listing. This gives clear guidance on appropriate usage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's 'Read-only; no side effects' is partly redundant. It does add genuinely new behavioral context: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes – useful preconditions an agent wouldn't infer from annotations.

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

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

Front-loaded with the core purpose and clearly sectioned into WHEN/NOT/RETURNS blocks. The freshness/CHA-SSA sentence is somewhat dense and internal-mechanism heavy, but every part is scannable and earns its place for an agent deciding how to call 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?

With no output schema, the description correctly carries the return-shape burden: it specifies the list contents (message text, file path, line number) and the empty-result case. Combined with usage and behavioral notes, 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 coverage is 100%, so term/limit/cursor/no_tests are already documented. The description restates the term filter with examples ('ErrInvalid', 'unauthorized') and implies pagination via 'empty when no matches found', but adds no semantics beyond 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?

States a specific verb ('Find') and resource ('error and panic sites'), then enumerates the exact patterns detected (errors.New, fmt.Errorf, sentinel var declarations, panic calls). It explicitly distinguishes itself from the sibling gograph_errorflow, 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?

Provides explicit WHEN TO USE scenarios (cataloging error codes, standardizing messages, checking whether a string exists) and an explicit NOT TO USE clause pointing to the alternative gograph_errorflow for propagation tracing. When/when-not/alternative are all covered unambiguously.

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 states 'Read-only; no side effects,' which aligns perfectly with annotations (readOnlyHint=true, destructiveHint=false). It also discloses caching and freshness behavior, explaining that the server checks freshness and retries CHA/SSA after source changes, adding significant context beyond 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?

The description is well-structured with clear sections and front-loads the purpose. It is slightly verbose in listing all included aspects, but each sentence adds value and does not waste space.

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

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

Despite lacking an output schema, the description sufficiently describes the return value: rich structured JSON with role, narrative, cross-references, and a not-found indicator. Given the tool's complexity and number of siblings, the description is complete enough for an agent to invoke correctly.

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

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

Only one parameter (symbol) exists with 100% schema description coverage. The description adds value by enumerating the supported formats (short name, dot-notation, fully-qualified ID), which is useful but not required. Baseline 3 is elevated to 4 due to this extra context.

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

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

The description uses a specific verb 'Generate' and specifies the exact resource: a synthesized, LLM-ready narrative for a Go symbol with a detailed list of included aspects (role classification, callers, callees, etc.). It clearly distinguishes from siblings like gograph_source and gograph_impact by contrasting use cases.

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 includes explicit 'WHEN TO USE' and 'NOT TO USE' sections, providing clear context for when the tool is appropriate (onboarding, PR docs, architectural assessment) and when alternatives like gograph_source or gograph_impact should be used 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?

Beyond the annotations (readOnlyHint/idempotent/destructive:false, which already establish the safety profile), the description adds genuine behavioral context: source analysis is refreshed before the call, possible dispatch is excluded from bundled identity impact and deep traversals, compact/deep are mutually exclusive, and question-like text is lexical rather than model-interpreted. 'Read-only; no persistent side effects' is redundant with the annotations, but the other disclosures are valuable and non-contradictory.

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 definition is dense but front-loads the core purpose before diving into modes, constraints, and return shape, so an agent can extract the essentials quickly. Some sentences are load-bearing (mutual exclusivity, dispatch exclusion, refresh behavior), though 'Read-only; no persistent side effects' duplicates the annotations and the overall length is on the heavy side.

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 multi-mode aggregation tool with no output schema, the description supplies the missing return-value information explicitly via the RETURNS block (shared gograph.explore.v1 with mode, selection_basis, ambiguity, totals, truncation, omission metadata) and covers mode defaults, limits, and exclusions. Nothing an agent needs to invoke this 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 description coverage is 100%, so the schema already documents all five parameters including the compact/deep exclusivity and the clamped 1-100 limit. The description reinforces mode defaults (5/25) but adds little semantic detail beyond what the schema provides, matching the baseline for full schema coverage.

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

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

The opening sentence gives a specific verb and resource (explore a lexical term or Go symbol) and frames the tool as a single bounded aggregation call that bundles matches, source, callers/callees, tests, and impact. It differentiates itself from the many focused siblings by noting that 'focused tools remain authoritative for complete output,' which tells an agent this is the bundled-overview option. The differentiation is meaningful though it references the sibling class generically rather than naming specific 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 description clearly explains the mode-selection conditions (compact for low-token discovery, deep for expanded evidence, mutual exclusivity, explicit limit overriding defaults) and when to prefer this over focused tools for complete output. It provides strong usage context but stops short of explicit when-not-to-use guidance or naming the specific alternative tools for a given task.

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 bare safety profile is covered. The description adds genuinely non-obvious behavior: a freshness check performed server-side, refresh in the requested analysis mode, and CHA/SSA retry for precise/precise_fallback graphs after source changes. It also states the empty-result case, though it does not discuss rate limits or how pagination interacts with graph snapshots.

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 labeled WHEN TO USE / NOT TO USE / RETURNS structure makes it scannable and front-loads the core action. It is somewhat dense with implementation detail about freshness and CHA/SSA retries, but each sentence carries routing or behavioral value; little is filler beyond the redundant 'Read-only; no side effects.'

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 correctly supplies the return shape (array of {name, type, tag}) and the empty/not-found case. Combined with schema-documented pagination and the annotations covering safety, 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 description coverage is 100%, so the schema already documents struct, limit, and cursor including bounds and byte-budget caveats. The description only implies the 'struct' argument's role ('named Go struct') and adds no syntax or format detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource ('Extract all declared fields from a named Go struct') and enumerates exactly what is returned: field names, Go types, and raw tag strings. It further distinguishes this from sibling tools by naming gograph_node/gograph_source for methods and gograph_literals for initialization sites, so an agent can route 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 clause covers three concrete scenarios (mapping serialization tags, inspecting layouts, enumerating fields before adding one), and the NOT TO USE clause names both alternatives and the conditions that select them (methods vs. initialization sites). 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 readOnly/idempotent/destructive, but the description adds genuine operational context: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. 'Read-only; no side effects' is redundant with annotations, but the staleness/retry behavior is real 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?

Well front-loaded: purpose first, then usage routing, then returns. However, the freshness/CHA/SSA retry sentence is fairly detailed implementation trivia that borders on noise for a selection decision. Still, structure is clean and labels (WHEN TO USE, NOT TO USE, RETURNS) make it scannable.

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

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

With no output schema, the description carries the return burden and does so explicitly (helper structs and factory functions, empty when none exist), plus the pagination behavior. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema fully documents package, limit, and cursor. The description only implies the package scoping ('for a named package') and says nothing about pagination or the limit/cursor semantics beyond what the schema already states. 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+resource: 'Find test helper structs and factory/builder functions declared in *_test.go files for a named package.' This precisely distinguishes it from gograph_tests (test functions) and shared-setup detection, so an agent can select it without opening the schema.

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

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

Includes explicit WHEN TO USE (before writing new tests, to avoid duplication) and NOT TO USE clauses that name alternatives: use gograph_tests for test functions exercising a symbol, and filesystem search for external test data files. 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 declare read-only, idempotent, non-destructive. Description adds: MCP server refreshes source analysis before call, and the tool has no side effects. It explains what the analysis does and doesn't do (path-insensitive). Adds value beyond annotations without contradiction.

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?

Description is well-structured with clear sections, front-loaded with purpose. It is informative but slightly verbose in the limitations part. Every sentence adds value; no wasted words. Could be tightened but still concise enough.

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?

Tool has 5 optional params, no output schema. Description compensates by stating returns include source, sink, severity, confidence, path steps. Provides context about analysis being path-insensitive and depth limit. Covers usage, limitations, and returns adequately.

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 each parameter having a description. The description adds marginal context: mentions configuring sanitizer policy via .gograph/flow.json for the config parameter. Baseline 3 is appropriate as 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?

Description clearly states it finds potential untrusted-data paths from specific sources (HTTP requests, JSON, env vars) to specific sinks (SQL queries, process execution, etc.). It uses a specific verb-resource pair. However, it does not explicitly differentiate from sibling tools, which are numerous but mostly unrelated to data-flow analysis. Slight deduction for lack of sibling differentiation.

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

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

Includes explicit 'WHEN TO USE' and 'NOT TO USE' sections, providing clear context and exclusions. It specifies appropriate scenarios (security review) and warns against misuse (as proof of exploitability). Also notes limitations (path-insensitive, 16-call depth). Perfect guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds freshness-check context and the CHA/SSA retry behavior on source changes, which is genuine behavioral value beyond the annotations. It does not describe pagination totals or failure modes beyond the empty-result case, so it stops 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 purpose followed by clearly labeled WHEN/NOT/RETURNS blocks; every sentence carries information. The behavior sentence about freshness and CHA/SSA retries is dense but not wasteful.

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

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

With no output schema, the description carries the return-shape burden and does so explicitly (files, symbol names, call edges, import paths, empty when package not found). Combined with annotations covering safety and the schema covering pagination, 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 names the package focus conceptually but adds no syntax or format detail beyond the schema, and says nothing about limit/cursor 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 (Extract) and resource (structural summary of one Go package) and enumerates exactly what it returns: files, defined symbols, internal call edges, and package-level imports. It also names the siblings it is not for, 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 (orienting to an unfamiliar package before editing) and NOT TO USE clauses that route to alternatives by name (gograph_context/gograph_source for a single symbol, gograph_query for global searches). 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/openWorldHint, so safety is covered. The description adds substantial non-obvious behavior: freshness checks before the call, refresh in the requested analysis mode, and CHA/SSA retry on precise/precise_fallback graphs after source changes. It stops short of describing pagination semantics fully, but goes well beyond the annotations.

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

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

Front-loaded with the core purpose, then clearly delimited WHEN TO USE / NOT TO USE / RETURNS sections. Slightly dense with the freshness/CHA-SSA detail, but every sentence carries information and headings aid scanning.

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

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

With no output schema, the description compensates by describing the return payload (variable names, types, mutating functions, empty case). Combined with usage guidance 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 schema already documents package, limit, and cursor (including byte-budget and cursor-snapshot semantics). The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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 (find) and resource (package-level variable declarations / var blocks) plus the secondary output (functions that mutate them) scoped to a specific package. It clearly distinguishes itself from siblings like gograph_envs and from local-scope variable analysis.

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 (mutable global state audits, thread-safety hazards, shared singletons before concurrency refactors) and NOT TO USE (local-scope vars; environment variable reads, routed to gograph_envs). The alternative is named with the condition that selects it.

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 and destructiveHint=false, and the description reinforces this with 'Read-only; no side effects.' Beyond that, it adds valuable operational context: the MCP server checks freshness, refreshes in the requested analysis mode, and retries CHA/SSA after source changes for precise graphs. No contradictions with annotations; the extra context enhances transparency.

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-structured with clear sections (purpose, behavior, thresholds, when to use, returns). It is longer than the high-reference example but every sentence contributes useful information. Slightly verbose, but the structure and front-loaded purpose make it easy to scan.

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

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

The description is complete for a moderately complex analysis tool. It covers purpose, thresholds and qualification logic, freshness/refresh behavior, usage guidelines, alternatives, and return format ('Ranked candidates with method, field, and call counts; empty when no threshold is exceeded'). No output schema exists, so describing returns is necessary and done well.

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

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

Schema covers all four parameters with descriptions and defaults (coverage 100%). The description goes further by explaining the qualification logic: 'Exceeding any enabled threshold qualifies a struct, and the combined excess determines rank.' It also restates defaults and clarifies that top limits results, adding semantic meaning beyond the schema's simple 'Minimum ...' labels.

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: 'Detect God Object anti-pattern candidates by scoring structs on method count, field count, and outgoing call count.' This clearly states what the tool does and highlights the unique scoring criteria, distinguishing it from sibling tools. The NOT TO USE section further clarifies its scope by contrasting with gograph_fields and gograph_complexity.

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?

WHEN TO USE is explicitly stated: 'During architecture reviews to find monolithic structs that should be decomposed.' NOT TO USE provides concrete alternatives: 'For general struct layout inspection (use gograph_fields); for single-function complexity (use gograph_complexity).' This is an exemplary model of when/when-not guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, but the description adds valuable context about freshness checking, mode-specific retry of CHA/SSA, and the rationale for excluding test files. This goes beyond the annotations without contradicting them.

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-structured with clear sections (main purpose, behavior, parameters, WHEN/NOT TO USE, RETURNS). Every sentence adds value without fluff, and the length is appropriate for the tool's complexity.

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 having no output schema, the RETURNS section specifies what the agent should expect: 'Ranked list of function names with fan-in count and package location.' Combined with behavior, params, and usage guidance, the description is fully self-contained 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?

While the schema covers 100% of parameters, the description adds meaningful semantics: 'top' default and 0 meaning, and include_tests explains why test helpers are excluded by default ('otherwise test helpers ... tend to dominate rankings'). This enriches the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Rank functions by incoming call count (fan-in)' which precisely identifies the tool's function. It also distinguishes it from siblings by noting alternatives in the NOT TO USE section, making the purpose unambiguous.

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

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

The description includes explicit WHEN TO USE and NOT TO USE sections, naming specific alternative tools: gograph_focus, gograph_coupling, gograph_complexity. This clearly guides the agent on when to select this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable non-obvious behavior: 'The MCP server refreshes source analysis before this call,' 'runtime environment values are never read,' pagination via 'next_cursor' tied to a 'same graph snapshot,' and the caveat that 'Construction is not dispatch proof.' That is substantive context beyond 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 description is dense but front-loaded: lead sentence states purpose, then scope exclusions, semantics, behavior, and return shape. Every sentence earns its place, though the wording is dense enough that a reader may need to parse carefully; it avoids 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?

Given three params, no output schema, and a read-only bounded list tool, the description supplies the needed return shape (gograph.results.v1 rows, total/returned/truncated/next_cursor), pagination behavior, and scoping caveats. It is nearly complete for invocation, with minor gaps around filtering semantics beyond the term option.

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 documents all three parameters with semantics (term matches method/URL/function, limit byte budget, cursor snapshot bounds). The description adds little beyond what the schema provides, so 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 precisely states the resource (HTTP evidence from net/http calls) and the exact syntactic constructs captured (Get/Post/PostForm/Head, NewRequest variants) while bounding scope. It explicitly names the sibling it replaces for server routes ('For server routes use gograph_routes'), making it distinguishable from the large sibling set.

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

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

The description clearly states what is included (static strings, bounded lexical base + static suffix) and what is excluded ('Client receiver methods and arbitrary URL-building functions are not inferred'). The routing pointer to gograph_routes is an explicit alternative. However, it doesn't describe when an agent should reach for this tool over, e.g., gograph_literals or gograph_endpoint, leaving some selection 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 carry read-only, idempotent, and non-destructive hints, so the description still adds meaningful context: the MCP server refreshes the graph first, canonical IDs survive line shifts but change on significant refactors, ambiguous names return all candidates instead of silently picking one. The 'read-only; no side effects' line matches annotations and adds no conflict.

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 purpose before complexity, and uses clear structural markers (all caps WHEN TO USE, RETURNS). It is dense, though perhaps slightly longer than minimal, with the canonical-ID mechanism explanation adding context that directly affects downstream usage rather than being 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 read-only two-parameter tool with no output schema, the description sufficiently explains the return envelope (gograph.identity.v1 JSON), the status cases (exact, ambiguous, not_found), deterministic behavior, and how the optional parameter resolves collisions. An agent could confidently invoke this for the intended use case without additional clarification.

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 descriptions are complete for both fields, and the description layers on meaning beyond the schema: it explains that the symbol can be an exact name, qualified spelling, or canonical stable ID, and that the package parameter specifically disambiguates a known in-package/external ID collision. This gives an agent richer decision-making for both parameters than the schema alone.

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 the specific operation ('Resolve') and resource ('Go symbol spelling or canonical stable ID') and clearly separates it from siblings by emphasizing location-independent symbol identity plus current source location, not merely looking up a graph node. It explicitly notes the handling of ambiguous short names, which further distinguishes its behavior from other graph 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 description provides a clear WHEN TO USE statement ('Before persisting cross-document references or to re-resolve an existing stable ID') that gives an agent actionable context for invoking the tool. It does not explicitly name alternatives or list when-not-to-use conditions, so it falls short of the strongest possible guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so 'Read-only; no side effects' is partly redundant. However the description adds substantial beyond-annotation behavior: a pre-call freshness check, refusal conditions for incomplete comparisons/deleted declarations/ambiguous identities, and the requirement to rebuild before traversing newly added symbols.

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 modes, usage guidance, returns, and constraints in a scannable order. It is dense and slightly long, but nearly every sentence carries actionable detail 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?

With no output schema, the description carries the return-value burden well: it lists the transitive upstream symbols, Mermaid flowchart text, bounded paging including empty pages, and the exact/possible distinction. Modes, constraints, and edge cases are all covered, leaving nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by framing the three mutually exclusive modes (symbol, uncommitted, since) and clarifying exact_only semantics (excludes paths relying on possible evidence) and mermaid output. It goes beyond the per-field schema text.

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

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

States a specific verb (traverse backwards), resource (call graph / symbols), and scope (full upstream blast radius), which immediately distinguishes it from the one-hop sibling gograph_callers. An agent can tell exactly what it computes 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 ('before refactoring a core function to see what breaks') and NOT TO USE ('for direct one-hop callers only, use gograph_callers') guidance. The alternative and the condition that selects it are both named.

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

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

Beyond annotations that already declare read-only/idempotent behavior, the description discloses non-obvious mechanics: production type-checked results are merged with AST-discovered test implementations because package loading excludes test variants. It also explains freshness checking and CHA/SSA retry behavior for precise graphs, which materially affects result interpretation.

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 purpose and uses clear WHEN TO USE / NOT TO USE / RETURNS sections. It is slightly overstuffed, and 'Read-only; no side effects' duplicates the annotations, but the additional behavioral details earn most of their space.

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

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

For a complex graph-analysis tool with no output schema, the description covers purpose, behavioral mechanics, alternatives, and return format. An agent has enough context to call it correctly and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including limit, cursor, interface, and test_only. The description adds only a brief restatement of test_only's purpose, which is already present in 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?

The first sentence states a specific verb and resource: 'Find all concrete structs that implement a named Go interface.' It explicitly distinguishes itself from siblings by naming gograph_interfaces for the inverse direction and gograph_fields for struct fields, so an agent can route correctly 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?

The description contains explicit WHEN TO USE and NOT TO USE sections. It names concrete scenarios (tracing polymorphism, dependency injection points, mocks) and points to the exact alternative tools for excluded cases (gograph_interfaces, gograph_fields).

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, openWorldHint=false. The description adds genuinely new context: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. The 'read-only; no side effects' line merely restates annotations, but the freshness/retry behavior is valuable. A 4 fits given annotations carry the safety profile.

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 structures WHEN/NOT-TO-USE and RETURNS cleanly. Dense but every section earns its place; slightly long due to the freshness/CHA-SSA detail, but not padded.

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

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

No output schema exists, but the description supplies a RETURNS section (file paths, package names, empty when unused) and covers the freshness/refresh behavior an agent needs to interpret results. Sufficient 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%; the package, limit, and cursor params are all documented in the schema, and the description's 'exact import path' wording reinforces the package format. It adds little beyond the schema, 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+resource+scope: 'Find all files and packages that import a specific package by its exact import path.' It explicitly names the siblings it is not (gograph_deps for outgoing imports, gograph_dependents for short-name reverse lookup), so an agent can disambiguate 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?

Contains explicit WHEN TO USE ('isolating usage of a third-party library before removing/replacing it, or tracing where an internal package is consumed from outside') and NOT TO USE clauses that route to gograph_deps and gograph_dependents. 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, closed-world behavior, so the safety bar is low. The description adds genuinely useful beyond-annotation context: freshness is checked before the call, a refresh happens in the current analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. It stops short of describing pagination or the empty-result edge case in depth.

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 one-line definition followed by clearly labeled WHEN/NOT/RETURNS sections. Some phrasing is dense (CHA/SSA retry detail) but each sentence carries distinct information; 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?

With no output schema, the description compensates by enumerating returns (interface names, method signatures, file locations) and the empty case. Combined with the explicit usage routing 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 schema already documents struct, limit (byte budget caveat), and cursor. The description restates that a struct name is the input and clarifies the subset semantics of the query, but adds no syntax or format detail beyond the schema. 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) and resource (Go interfaces satisfied by a struct), and explicitly frames itself as the inverse of gograph_implementers via duck-typing resolution. An agent can distinguish 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?

Includes explicit WHEN TO USE (know which contracts a struct implicitly fulfills, e.g. before refactoring a method) and NOT TO USE clauses that name the correct alternatives (gograph_implementers for the inverse, gograph_node/gograph_public for interface declarations). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds non-obvious behavior: a freshness check before the call, a refresh in the requested analysis mode, and CHA/SSA retry on precise graphs after source changes. That is genuine context beyond structured fields, though it could clarify result caching or pagination interaction.

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 labeled WHEN/NOT/RETURNS blocks that are easy to scan. Slightly dense, particularly the analysis-mode freshness sentence, but every section earns its place.

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

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

With no output schema, the description supplies the return contract itself (file paths and line numbers, empty when no sites), plus usage conditions and behavioral caveats. Nothing an agent needs to invoke and interpret this tool is missing.

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

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

Schema coverage is 100%, so the struct, limit, and cursor semantics are already fully documented in the schema (opaque next_cursor, byte-budget caveat). The description reinforces the 'named struct' concept but adds no syntax or format detail beyond the schema, so 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 precise verb (find) and resource (composite-literal initialization sites for a named Go struct) and clarifies with concrete syntax Foo{...}. It distinguishes itself from siblings by naming gograph_constructors and gograph_envs, so an agent can separate it 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 (scoping a required-field migration blast radius) and NOT TO USE sections that name the correct alternatives for excluded cases (gograph_envs/grep for magic values, gograph_constructors for factory functions). No inference required to route correctly.

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 readOnly/idempotent/no-destructive, so 'Read-only; no side effects' is redundant. However the description adds genuinely non-obvious behavior beyond the annotations: the server checks freshness before the call, refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. The empty-result behavior is also disclosed.

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 before the equivalence note, then cleanly sectioned as WHEN TO USE / NOT TO USE / RETURNS. Slightly dense in the middle where the graph-freshness mechanics are packed into one long sentence, 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?

With no output schema, the RETURNS section correctly compensates by describing the return shape (test-file struct names with file locations, empty when none exist). Purpose, alternatives, behavior, and return values are all covered for a 3-parameter 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%, and the schema already documents limit, cursor, and interface (including the 'AuthService' example), so the baseline is 3. The description adds nothing further about parameter syntax, pagination usage, or how cursor interacts with the freshness/retry behavior described.

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 structs in *_test.go files that implement a named interface') and sharpens it with the domain gloss ('test doubles, mocks, and stubs'). It also declares its exact equivalence to the sibling gograph_implementers(test_only=true), so an agent can distinguish it from siblings 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?

Contains explicit WHEN TO USE and NOT TO USE sections, names the alternative (gograph_implementers without test_only) for the production case, and even recommends the canonical call for new code. There is no ambiguity left about when this tool is the right choice.

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 redundantly restates 'Read-only; no side effects'. It does, however, add real behavioral context: the server re-refreshes in the requested analysis mode, a precise graph widens detection (++/+=, pointer-alias, atomic/sync/wrapper, channel), and analysis re-runs after source edits.

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 labeled WHEN/NOT/RETURNS sections make it scannable. Slightly dense in the middle sentence about analysis modes, but every sentence carries information and nothing 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?

Covers selection constraints, freshness/re-analysis behavior, and return contents (mutation locations plus indirect mutator method names), which compensates for the absent output schema. Pagination is documented in the schema via limit/cursor.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the 'Type.Field' qualified form for the required field parameter, which disambiguates same-named fields across unrelated types, and by stating the exclusion of local-variable assignments.

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 struct-field and package-global mutation sites', which is a distinct capability from siblings like gograph_fields or gograph_usages. The scope qualifiers (excludes ordinary local-variable assignments) further sharpen what is returned.

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 clauses that name the correct alternatives: gograph_fields for declarations, gograph_literals for whole-struct initialization. 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 establish read-only, idempotent, non-destructive behavior, but the description adds meaningful context: the MCP server checks freshness before the call, refreshes in the requested analysis mode, and precise graphs retry CHA/SSA after source changes. It also states empty return when the name is not found.

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

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

Purpose is front-loaded, followed by WHEN TO USE, NOT TO USE, and RETURNS sections. The structure is clean and every sentence contributes selection or behavior information.

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

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

No output schema exists, but the description explains the return shape (node properties array with kind, file, line, signature) and the empty-result case. Combined with the schema covering pagination parameters, it is complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents name, limit, and cursor in detail. The description's 'symbol, package, or file' phrase loosely maps to the name parameter but adds no syntax or format detail beyond the schema, making baseline 3 appropriate.

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

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

The description states a specific verb and resource (fetch AST metadata for symbol/package/file) and enumerates returned fields. It explicitly distinguishes itself from gograph_source and gograph_callers/gograph_callees, so an agent can choose correctly without opening schemas.

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

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

It has explicit WHEN TO USE and NOT TO USE sections, names the relevant alternatives (gograph_source, gograph_callers, gograph_callees), and gives the selecting condition (metadata-only lookups vs full source or call relationships).

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 adds substantial beyond that: the MCP server checks freshness and refreshes in the requested analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. It also discloses the algorithm (full BFS reachability), which affects result interpretation.

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, then labeled WHEN TO USE / NOT TO USE / RETURNS sections that make scanning easy. Dense but every clause carries information; the middle sentence on freshness/retry is somewhat heavy but genuinely useful.

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

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

No output schema exists, yet the description covers returns (orphan symbols with package paths and file locations, empty = none detected) plus pagination via the schema. For a read-only analysis tool, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% for both params (limit, cursor), and the schema already explains the byte budget and opaque cursor semantics. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('Find functions and methods unreachable from runtime roots') and precisely enumerates what counts as a root (main/init, test/benchmark/fuzz, HTTP route handlers, eligible external exports, with internal/ exclusion). An agent can distinguish this dead-code detector from gograph_usages, gograph_callers, and gograph_untested 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 ('During code cleanup or dead-code audits') and NOT TO USE with named alternatives ('For checking one symbol's usages use gograph_usages or gograph_callers'). Routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine beyond-annotation context: the ranking rules (exact before possible, shorter, production before tests, typed before heuristics), the canonical tie-breaker, and that the server refreshes source analysis before the call. It does not cover error/failure 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-loads the purpose, then organizes ranking rules, mutation/safety note, and WHEN/NOT/RETURNS blocks. Slightly dense with the ranking sentence, but each clause carries meaning and nothing 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?

There is no output schema, so the explicit RETURNS section (from, to, found, steps[], plus Mermaid text when mermaid=true) fills that gap. Combined with usage routing and ranking 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 all three parameters are already documented in the schema. The only added hint is 'with mermaid=true, Mermaid flowchart text,' which largely restates the mermaid parameter's own schema description. Baseline 3 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 the best call chain from one symbol to another.' It also distinguishes itself from the sibling gograph_impact by name, so an agent can route correctly without opening schemas.

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

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

Contains explicit WHEN TO USE ('confirm reachability between non-adjacent symbols') and NOT TO USE ('for all transitive upstream callers, use gograph_impact') sections, naming the alternative and the condition that selects it. 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, yet the description adds real behavioral context: the server checks freshness before the call, retries CHA/SSA for precise modes, uncommitted modes compare declarations against HEAD, and consumers refuse incomplete comparisons or missing/ambiguous graph identities. This is disclosure well beyond the structured hints.

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

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

Front-loaded with the core purpose and well-organized into WHEN/NOT/RETURNS blocks. It is dense and long, and 'Read-only; no side effects' partially restates the readOnlyHint annotation, but nearly every sentence carries actionable information.

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

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

With no output schema, the description compensates by fully describing the JSON return shape (inspect_first[], tests[], routes[], env[], risk object, inspect_contexts[] with with_context). Combined with the freshness and refusal semantics, 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: with_context=true inlines full source/callers/callees and eliminates follow-up gograph_context calls, and uncommitted=true produces a global plan for all uncommitted changes. Only the symbol parameter's short/dot/fully-qualified forms are left 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 ('Generate') and resource ('structured pre-edit plan for a target symbol') and enumerates the plan's contents (symbols to read first, tests, routes, env vars, public-API/SQL risk). It distinguishes itself from siblings by naming gograph_review and gograph_context 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?

The WHEN TO USE / NOT TO USE block is explicit: use before multi-file refactoring or architectural changes; do not use for trivial single-line fixes or post-edit verification, and it routes the latter to gograph_review. The with_context guidance further tells the agent how to avoid follow-up gograph_context calls.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description goes beyond that by disclosing the server-side freshness check and refresh in the current analysis mode, and the CHA/SSA retry after source changes, plus empty-result semantics — meaningful operational behavior not captured by 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 purpose, then uses clearly delimited WHEN TO USE / NOT TO USE / RETURNS blocks. Each sentence carries distinct information (scope, freshness behavior, routing, empty-result behavior) with no 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?

With no output schema, the description compensates by describing the return shape (exported symbol names with kinds and file locations, empty when no exports or package not found). Combined with annotation coverage and freshness notes, 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 package, limit, and cursor are already documented in the schema (including the byte-budget note and opaque cursor semantics). The description adds no parameter-level 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?

States a specific verb and resource ('List all exported (public) symbols of a specific package') and enumerates the kinds returned (functions, methods, types/interfaces, variables, constants). It also scopes itself against siblings by naming the private-symbol and drift alternatives, 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?

Contains explicit WHEN TO USE (reviewing a package's public contract, integration docs, checking exposure) and NOT TO USE conditions with named alternatives: gograph_node/gograph_focus for unexported symbols and gograph_api for drift against a baseline. This is textbook 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 declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the server refreshes source analysis before the call, multiple terms use OR semantics, and results are empty when no terms match. It stops short of describing pagination/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-loads the core purpose, then uses labeled WHEN/NOT/RETURNS sections. Each sentence carries distinct information and there is no redundancy or 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 steps in to describe return values (matching symbols, files, imports; empty on no match) and pagination is hinted via the cursor semantics. For a search tool with full annotation and schema coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents term, terms (OR semantics), limit (byte budget caveat), and cursor. The description largely restates the OR semantics already present in the schema and adds little new parameter-level meaning. 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 (Search) and a well-scoped resource (graph index for symbols, packages, files, and import edges), plus the matching mechanism (keyword substrings). An agent can distinguish it from siblings like gograph_source and gograph_deps 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 (initial exploration with a keyword but unknown package) and NOT TO USE clauses that name the exact alternatives (gograph_source, gograph_node for known symbols; gograph_deps for dependency trees). Routing is fully specified.

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 behavior. The description adds meaningful non-annotation context: freshness checking, conditional CHA/SSA retry after source changes, and the empty-result case, though it also redundantly repeats 'Read-only; no side effects.'

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

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

The description is front-loaded and structured with WHEN TO USE, NOT TO USE, and RETURNS labels. It is mostly efficient, but repeats the read-only/no-side-effects point already covered by annotations and includes implementation-level CHA/SSA detail that is useful but not tightly edited.

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 supplies the return shape, classification values, and empty-result behavior. It also covers freshness and retry behavior, making the definition complete enough for an agent to call the tool and interpret its results.

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

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

Schema description coverage is 100%, so the schema already documents function, limit, and cursor semantics. The description names the function parameter and return classifications but adds no syntax, constraints, or edge cases beyond what the schema provides.

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

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

States a specific verb ('Show how each caller uses') and resource ('return value(s) of a named function'), with clear distinctions from sibling tools in the NOT TO USE section. An agent can tell it apart from gograph_callers and gograph_errorflow without opening schemas.

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

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

Provides explicit WHEN TO USE guidance tied to a concrete scenario (changing a function's return signature) and NOT TO USE guidance naming the alternative tools gograph_errorflow and gograph_callers. Routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: freshness checking and refresh behavior, CHA/SSA retry on the precise graph, mode-dependent semantics ('Uncommitted modes compare declarations against HEAD, including selected untracked Go files'), and refusal conditions (incomplete comparisons, deleted declarations, missing/ambiguous identities). This is rich behavioral disclosure.

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

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

Front-loaded with the core purpose and clearly segmented into WHEN TO USE / NOT TO USE / RETURNS sections, so structure aids scanning. It is somewhat verbose, with internal engine details ('precise and precise_fallback graphs retry CHA/SSA', 'Current-graph consumers refuse...') that are informative but border on excess for a selection-time 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 no output schema present, the description compensates by describing the RETURNS shape (changed_symbols[], tests[], routes[], env[], errors[], risk object with public_api/touches_sql/touches_routes/touches_env). Combined with usage rules and refusal conditions, an agent has everything needed 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 coverage is 100%, so the schema documents both params and the baseline is 3. The description adds value the schema lacks: it states the mutual requirement ('Requires either symbol or uncommitted=true') and clarifies what uncommitted=true actually reviews ('all current unstaged changes at once'), which is more precise than the schema's 'uncommitted/modified changes'.

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

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

The description opens with a specific verb+resource: 'Summarize the scope and risk profile of a change', and immediately enumerates the dimensions covered (changed symbols, covering tests, routes, env vars, SQL). It further differentiates itself from siblings by explicitly naming gograph_boundaries and gograph_plan as alternatives for other jobs.

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 guidance ('After editing — as a post-edit verification step before committing') and a NOT TO USE section routing to gograph_boundaries for boundary enforcement and gograph_plan for pre-edit planning. It also states the invocation condition: 'Requires either symbol or uncommitted=true', and explains the uncommitted=true usage.

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, and the description adds real behavioral context: freshness checking before the call, graph-mode retries (CHA/SSA), and current-graph consumer refusal conditions (incomplete comparisons, deleted declarations, ambiguous identities). This goes well beyond the annotation surface.

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

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

Front-loads purpose and organizes content into usage, exclusion, and return sections. However, the trailing sentences about graph consumers, declaration census, and rebuilds are dense implementation detail that could crowd out agent-relevant guidance.

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 supplies a RETURNS section (title, results[], scores, verdicts, breakdown metrics, optional message) and covers uncommitted-mode behavior. An agent has enough to call and interpret it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a meaningful constraint not captured by the schema: 'Requires either symbol or uncommitted=true' (schema marks neither required). This clarifies mutual-requirement semantics for the two params.

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

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

States a specific verb and resource ('Evaluate the change risk profile of target symbol(s) or uncommitted changes') and spells out what the score combines (blast radius, complexity, coverage, dependencies). The explicit WHEN/NOT TO USE clauses naming gograph_review and gograph_plan let an agent distinguish it from the large sibling set without opening schemas.

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

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

Provides explicit 'WHEN TO USE: Before committing edits...' and 'NOT TO USE: ... use gograph_review ... use gograph_plan' guidance. The routing conditions are unambiguous and name the concrete alternatives.

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

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

Annotations already cover readOnly/idempotent/no-destructive, so the bar is lower, yet the description adds substantial non-annotation behavior: the server refreshes source analysis before the call, pages are capped at 64 KiB to avoid spilling to an out-of-band file, Gin/Fiber vs Echo handler-resolution rules differ, constant Group/Route prefixes are composed, and dynamic prefixes stay unresolved. These are real operational traits an agent cannot infer from the schema or hints.

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

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

Front-loaded with purpose, then caveats, then WHEN TO USE/NOT TO USE and RETURNS. Dense but every sentence carries information; the framework-specific handler-resolution detail is the only passage bordering on over-explanation for a listing 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, so the description compensates by naming the gograph.routes.v1 payload shape (total, returned, truncated, routes[], next_cursor). Combined with pagination limits, test inclusion, and module resolution semantics, 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 coverage is 100%, so the baseline is 3; the description goes slightly beyond by framing cursor reuse as continuing the 'same filtered census' and explaining that limit interacts with the 64 KiB byte budget (the page may return fewer than limit rows). Most param text overlaps the schema, so it is not a full 5.

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

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

Specific verb (List) + resource (HTTP routes) + explicit scope (deterministic bounded page) with the returned fields enumerated. The WHEN TO USE / NOT TO USE block names gograph_endpoint as the sibling for downstream call chains, so an agent can distinguish it from the surrounding gograph_* tools without opening any schema.

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

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

Contains an explicit WHEN TO USE (inventory one service/module, find a route before gograph_endpoint) and NOT TO USE (handler downstream call chain → use gograph_endpoint). The condition selecting the alternative is stated, not implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent ("Read-only; no side effects"). It adds genuinely new behavioral context beyond annotations: freshness checking before the call, refresh in the requested analysis mode, and CHA/SSA retry after source changes in precise modes.

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 clearly sectioned WHEN TO USE / NOT TO USE / RETURNS. Efficient overall, though the freshness/CHA-SSA sentence is dense and slightly tangential to selection.

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 supplies the return shape (struct names, package paths, file locations, empty result semantics). Combined with purpose, usage, and behavioral notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents table, limit, and cursor with clear semantics. The description adds no parameter-level detail beyond the schema, 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 states a specific verb (find) and resource (Go structs mapping to a DB table via struct tags) with concrete examples of the tag forms (db:"table_name", gorm:"table:table_name"). It is clearly distinguishable from siblings like gograph_fields, gograph_query, and gograph_sql.

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 (tracing which types represent a table, pre-migration ORM model inspection) and NOT TO USE (non-tagged structs as query results) with named alternatives gograph_fields and gograph_query. 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.