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=true and destructiveHint=false, and the description adds 'Read-only; no side effects.' More importantly, it discloses path traversal constraints: 'explicit paths must remain inside the analyzed project, and every path component plus the final regular file is read through the rooted repository boundary,' providing context not 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 front-loaded with the main purpose, followed by details, usage guidance, and return value. While slightly verbose, each section (WHEN TO USE, NOT TO USE, RETURNS) is structured for quick scanning. Minor redundancy with annotations ('Read-only; no side effects') prevents a perfect score.

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 covers the purpose, usage context, safety constraints, and returns ('Structured pass state and boundary violations'). It does not describe error behavior if the config is missing, but it mitigates this by pointing to gograph_boundaries_create for setup.

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 a single optional config parameter. The description adds value by reiterating the default ('.gograph/boundaries.json') and introducing a non-obvious constraint: explicit paths must remain inside the analyzed project, which is more precise than 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 clearly states the tool's function with a specific verb and resource: 'check package imports against a boundaries.json configuration.' It also distinguishes itself from siblings by explicitly naming alternatives for unconstrained dependency exploration (gograph_deps, gograph_coupling) and referencing gograph_boundaries_create for creation.

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 section explicitly prescribes 'In CI gates or post-edit reviews to enforce layer separation.' NOT TO USE section provides a clear exclusion and names alternative tools, giving the agent explicit decision criteria for 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 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=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond these by noting the MCP server refreshes source analysis before the call and that the operation is read-only with no persistent side effects. It also explains depth-default and traversal expansion behavior, which is useful operational context.

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

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

The description is compact and logically organized with clear sections: action, default behavior, side-effect note, WHEN TO USE, NOT TO USE, and RETURNS. No sentence is wasted; all content is directly actionable for an AI agent.

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 graph-traversal tool with no output schema, the description covers the essential contextual needs: purpose, default depth behavior, side-effect profile, source-refresh behavior, return value composition (package paths, file locations, line numbers), and alternative tools. Annotations cover safety and idempotency, so 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?

Input schema already has 100% parameter description coverage, so the baseline is 3. The description adds meaning by explaining that depth defaults to one-hop fan-out and that depth 2-10 expands the downstream call graph, and by describing the mermaid=true return format. This enriches the schema's parameter descriptions with contextual semantics.

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

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

The description opens with a specific verb and resource: 'Find functions and methods called by the specified function.' It clearly identifies the traversal direction (fan-out to callees) and explicitly distinguishes itself from gograph_callers and gograph_deps in the usage guidance, making sibling differentiation strong.

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, naming alternative tools (gograph_callers for upstream callers, gograph_deps for package dependency trees). This gives the agent unambiguous criteria for selecting this tool over closely related siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds valuable behavioral context beyond those hints: it explains that the MCP server refreshes source analysis before the call, describes how Interface.Method expands through all recorded implementations but reports a shared source call site once, and notes the 'precise graph' conditioning. No contradictions with 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 a concise opening summary, labeled WHEN TO USE / NOT TO USE sections, and a RETURNS section. Every sentence provides distinct value—no filler or repetition of schema fields. The use of labeled sections makes the information easily scannable for an agent, and the length is proportionate to 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?

Given the moderate complexity of the tool (depth handling, interface dispatch, alternative tools) and the absence of an output schema, the description compensates fully: the RETURNS section specifies caller symbols with package paths, file locations, call-site line numbers, and Mermaid text option. It also covers the freshness behavior and excludes unbounded blast radius. The description is complete for an agent to select and 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for key parameters: it explains depth semantics ('Defaults to one-hop fan-in; depth 2-10 expands callers-of-callers'), elaborates on the 'function' parameter's interface notation behavior, and clarifies the mermaid=true return type. It does not discuss no_tests or exact, but the schema already describes those adequately.

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

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

The description opens with a specific verb and resource: 'Find functions and methods that call the specified function or interface method.' It clearly identifies the tool as a fan-in caller analysis and distinguishes it from related tools by noting one-hop default vs. depth expansion and interface method expansion through implementations. The explicit mentions of gograph_impact and gograph_callees as alternatives reinforce the unique purpose.

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 section ('Before renaming, removing, or changing a function or interface method signature') and NOT TO USE section with named alternatives ('use gograph_impact' for upstream blast radius, 'use gograph_callees' for downstream callees). This gives the agent clear decision criteria for 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces 'Read-only; no side effects' and adds context about the server prerequisite, caching recommendation, and that the return includes known limitations. This adds useful behavioral context beyond the annotation baseline, though it doesn't reveal any surprising behaviors.

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, prerequisites, side-effect statement, WHEN TO USE, NOT TO USE, and RETURNS. Every sentence serves a distinct purpose, and it's concise enough to read quickly without wasted words.

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

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

For a zero-parameter tool with no output schema, the description is complete: it explains what the tool does, when to use it, how often, prerequisites, return format, and even known limitations. The annotations cover safety, so no gaps remain in context.

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 has zero parameters, and schema coverage is 100% (empty object). The description doesn't need to explain parameters but does describe the return value (structured JSON with tool names, purposes, workflows, limitations), which is helpful for an agent deciding what to expect. Baseline of 4 fits given no parameters to document.

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 verb 'List' and the resource 'all available gograph MCP tools' along with their purposes and recommended agent workflows. This distinguishes it from sibling tools, which are analytical or graph-specific, by positioning it as a meta-orientation tool.

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

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

The description includes explicit 'WHEN TO USE' (call once per session to orient before analytical queries) and 'NOT TO USE' (do not repeat after capabilities are cached), plus a prerequisite ('once the project-scoped MCP server has started, no graph-state prerequisite'). This gives clear guidance on when to invoke it 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?

While annotations already declare readOnly, idempotent, and non-destructive, the description adds substantial behavioral context: it explains the dual-mode semantics (with and without git_ref), details that 'deleted' in working-tree mode includes absent/ignored/build-inactive files, and notes that without git_ref it compares against trusted persisted graph.json without refreshing. This goes well beyond the structured annotation 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 well-structured with clear labels (WHEN TO USE, NOT TO USE, RETURNS) and front-loads the core action. Each sentence adds information about modes, exclusions, or return values; there is no filler. Despite its length, it remains efficient and 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?

Given the tool's nuance (modes, exclusions, return semantics), the description is complete. It covers what it does, when to use it, behavior in each mode, what it returns (grouped by added/modified/deleted with empty arrays), and explicitly notes it is read-only. No output schema exists, so the description correctly takes on the responsibility of describing return values.

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 only says git_ref is an optional git reference string. The description enriches this by explaining the behavioral difference when git_ref is omitted (uses persisted graph.json) versus provided (refreshes analysis and diffs against the reference). This is crucial semantic information that 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 description opens with a specific verb and resource: 'List Go symbols that have been structurally modified, added, or deleted.' It clearly distinguishes itself from related tools by explicitly naming git diff for line-level diffs and gograph_impact for blast radius, making the tool's unique purpose unmistakable.

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, stating to use this tool after editing to confirm symbol changes before gograph_impact or gograph_review, and not for line-level diffs (use git diff) or blast radius (use gograph_impact). This is textbook guidance on when and when not to invoke the tool.

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

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

Annotations already convey read-only, idempotent, non-destructive hints. The description adds valuable context beyond those hints: it details how relative vs absolute config paths are handled, explains that baselines ending in .json load a saved graph with specific constraints, and notes that Git refs are extracted temporarily. This meaningfully expands the agent's understanding, though it doesn't cover every possible behavior (e.g., error conditions).

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 ideal, with several nested clauses, but it is well-structured with labeled sections (WHEN TO USE, NOT TO USE, RETURNS) and front-loads the main purpose. Each sentence contributes important safety and usage detail, so the length is justified despite being somewhat dense.

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 tool is complex—it aggregates many checks and has nuanced config/baseline logic—and there is no output schema. The description addresses this by listing the checks, explaining config confinement and baseline semantics, and stating the return structure (pass/warn/fail status, findings, summary counts). It is sufficiently complete for an agent to decide when and how to invoke it, though some technical details are compressed.

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 covers all 3 parameters with descriptions, providing a solid baseline. The description adds extra semantic nuance, particularly around config path confinement and baseline handling (saved graph versus Git ref), which maps to the 'config' and 'since' parameters. This goes beyond simply restating the schema, though not every parameter is individually explained in prose.

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 this tool refreshes source analysis and runs static policy checks, enumerating the specific check categories (boundaries, API drift, changed-route/export tests, coverage, etc.). It distinguishes itself from the many sibling analysis tools by serving as a consolidated policy-check/aggregate tool, and the WHEN TO USE/NOT TO USE sections reinforce its intended purpose.

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 usage guidance: 'WHEN TO USE: During PR review or pre-commit analysis' and 'NOT TO USE: For CI process exit enforcement (use CLI gograph gate).' This directly tells the agent when to choose this tool over alternatives and even names the specific alternative. It also clarifies config-path confinement for safe 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 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?

The description goes well beyond annotations by disclosing freshness/refresh behavior (server checks freshness, retries CHA/SSA in precise modes), defining what is not indexed (channel receives/select), and confirming read-only semantics. This is valuable context not available in annotations.

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

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

The description is well-structured with labeled sections and every sentence contributes meaning. It is slightly verbose in the freshness mechanics, but still appropriately sized and front-loaded with the primary 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?

With no output schema, the description explains return values (file locations, line numbers, primitive kind) and empty behavior. It also covers exclusions and refresh behavior, making it highly complete for a tool with only one optional parameter.

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 sole 'term' parameter, and the description repeats the same examples given in the schema. It adds no new semantic meaning beyond the schema, placing it at the baseline for adequate coverage.

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

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

The description clearly states the tool identifies 'indexed concurrency sites' and enumerates specific resource types (goroutine spawns, channel sends, sync calls). It distinguishes from siblings by explicitly noting sequential flow analysis should use gograph_callers/gograph_callees.

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 provide clear conditions (e.g., auditing race safety, async flow, synchronization points) and direct the agent to alternatives for sequential analysis. This is ideal 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?

Describes freshness checking, refresh behavior in different analysis modes, and retry logic for CHA/SSA after source changes. This adds significant context beyond the annotations, which already indicate read-only and idempotent. No contradiction with 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 structured with clear sections (purpose, freshness behavior, read-only, usage, returns). It is somewhat lengthy but every part adds value; front-loading with the core purpose is effective. A minor trim could be possible.

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 no output schema, the description specifies the return type: list of constructor names with signatures, package paths, file locations, and empty case. It covers all relevant aspects: behavior, usage prerequisites, and output format, making it fully contextual for an AI agent.

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 a well-described single parameter 'struct'. The tool description does not add further semantics beyond what the schema already provides, so a baseline score 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?

The description clearly states the tool finds factory/constructor functions that instantiate named Go structs, with a specific condition on return types. It differentiates from sibling tools like gograph_literals and gograph_fields in the NOT TO USE section.

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 provide clear guidance: use when looking for canonical construction or before modifying initialization; avoid for literal sites or fields. Also names alternative tools.

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 declare readOnlyHint=true, but the description adds context about freshness checks, retry of CHA/SSA after source changes, and the side effect of appending telemetry in an audit session. This goes beyond 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 long but well-structured with labeled sections (purpose, WHEN TO USE, NOT TO USE, RETURNS). Every sentence conveys needed information, though some redundancy exists with the schema.

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

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

No output schema exists, so the description's 'RETURNS' section fully lists the response structure, including the empty-object case and the uncommitted contexts[] variant. This makes the tool's behavior predictable.

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 each parameter is already documented. The description reinforces uncommitted=true behavior but does not add substantial detail beyond the schema definitions.

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 a pre-flight context bundle for a single Go symbol', listing exact contents (AST metadata, source, callers, callees, tests, role). This clearly distinguishes it from sibling tools like gograph_callers or gograph_tests.

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' states it is the first call before editing to eliminate 4–5 roundtrips. 'NOT TO USE' names alternatives: gograph_focus for package-level orientation and gograph_impact for transitive blast radius.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read-only; no side effects' and adds non-obvious behavior: 'The MCP server refreshes source analysis before the call.' This provides useful context beyond 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 four sentences, front-loaded with purpose, and every sentence contributes value (purpose, refresh behavior, usage boundaries, return format). It repeats annotation information ('Read-only; no side effects') but not so much that it harms clarity.

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 tool with no output schema, the description covers what it returns, when to use it, when not to use it, and a key behavioral detail about automatic source refresh. This is complete enough for an agent to select and invoke the tool correctly in context.

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% (both 'package' and 'mermaid' have descriptions). The description adds little beyond the schema—only noting that mermaid=true returns Mermaid flowchart text, which the schema already communicates. Baseline 3 is appropriate since structured data carries the parameter semantics.

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

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

The description uses a specific verb 'Find' with a clear resource 'all packages that import the named package' and explicitly calls itself the inverse of gograph_deps, distinguishing it from the sibling tool. It also differentiates from gograph_callers for function-level queries, so purpose is 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?

Provides explicit 'WHEN TO USE' and 'NOT TO USE' sections, with a named alternative (gograph_callers) and a concrete use case (before package-level interface change or removal). This is exactly the guidance an agent needs to decide between siblings.

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

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

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds context about freshness checks, analysis mode refreshes, and retry behavior for precise graphs. It also reiterates 'Read-only; no side effects.' No contradiction 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?

The description is well-structured: a concise purpose statement, followed by technical behavior, usage guidance, return format. Every sentence adds value, and the most critical information is front-loaded.

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

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

Given no output schema, the description lists return format (embedding parent struct names with package paths and file locations) and edge case (empty when nowhere embedded). The freshness mechanism is also explained. All necessary context for tool invocation is present.

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 single parameter 'struct' has a schema description with examples (e.g., 'Symbol', 'PackageNode'), and the overall description reinforces what the parameter represents. Schema coverage is 100%, so the descriptive addition is helpful but not essential.

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 immediately states the action: 'Find all Go structs that embed the named struct via anonymous field composition.' It clearly identifies the resource and scope, and distinguishes from sibling tools like gograph_implementers and gograph_usages.

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 includes explicit 'WHEN TO USE' and 'NOT TO USE' sections, specifying concrete scenarios (e.g., understanding base type extension, estimating blast radius) and alternatives for interface implementations and named field references.

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 indicate read-only, idempotent, non-destructive. The description adds detail on freshness checks, analysis mode refreshes, and retry behavior for precise/precise_fallback graphs, going 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?

The description is well-structured with clear sections (WHEN TO USE, NOT TO USE, RETURNS). It is concise, every sentence serves a purpose, and the main functionality is front-loaded.

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

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

For a static analysis tool with one optional parameter and no output schema, the description covers purpose, usage guidelines, parameter semantics, and return values (list of env key names, calling function, file/line). No 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?

Schema coverage is 100% for the single optional parameter. The description adds valuable context: the `term` filters by key name substring with an example (e.g., 'DATABASE' matches DATABASE_URL and DATABASE_HOST), clarifying fuzzy matching behavior.

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 verb 'Find' and the resource 'environment variable reads', specifying the exact functions (os.Getenv, os.LookupEnv) and config frameworks. It distinguishes from sibling tools like gograph_sql, making its purpose unmistakable.

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, listing concrete scenarios like compiling deployment manifests or auditing secrets, and excluding runtime env reading or database queries with an alternative tool reference.

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 declare readOnly/idempotent/destructive hints, but the description adds meaningful operational behavior: freshness checking, refresh in requested analysis mode, CHA/SSA retry for precise graphs, and explicit 'Read-only; no side effects.' This goes well beyond the structured metadata and provides context an agent needs for execution.

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

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

The description is dense but well-organized with labeled sections (WHEN TO USE, NOT TO USE, RETURNS) and no redundant sentences. Every sentence conveys distinct information, and the most critical purpose statement 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?

Given no output schema, the description compensates by specifying the return shape (list of sites with message, file path, line number) and empty-result behavior. It also covers freshness/read-only semantics and usage context, making it complete for an agent to select and 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining term filters by 'message substring' with examples ('ErrInvalid', 'unauthorized'). However, it does not mention the no_tests parameter, though the schema does document it; this is a minor gap given the schema already describes 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?

The description opens with a specific verb and resource ('Find all error and panic sites') and enumerates the exact code patterns covered (errors.New, fmt.Errorf, sentinel var declarations, panic calls). It clearly distinguishes this tool from sibling gograph_errorflow by stating it catalogs error sites, not propagation paths.

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 provide concrete use cases (cataloging error codes, standardizing messages, checking before defining a new error) and name the alternative (gograph_errorflow for tracing propagation). This is exemplary guidance.

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

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

The 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?

Describes freshness checking, retry behavior in analysis modes, and confirms read-only with no side effects, adding context beyond the readOnlyHint, idempotentHint, and destructiveHint 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?

Well-structured with separate sections, but slightly verbose. Could be trimmed while retaining key 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?

Covers all necessary information: purpose, usage guidance, behavioral traits, parameter description, and return format ('Array of field entries'). No output schema needed.

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 single parameter 'struct' is fully described in the schema (100% coverage). The description adds minimal extra meaning (e.g., 'named Go struct'), so baseline 3 is appropriate.

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

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

The description clearly states it extracts declared fields from a named Go struct, listing field names, types, and tag strings. It distinguishes from siblings like gograph_node and gograph_literals.

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

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

Explicitly provides 'WHEN TO USE' and 'NOT TO USE' sections with specific examples (mapping serialization tags, inspecting layouts vs. methods/initialization sites).

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 discloses read-only nature, freshness checking, and refresh behavior in different analysis modes. Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context about graph mode specifics and retry behavior, exceeding the annotation baseline.

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

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

The description is well-structured with clear sections (action, behavior, usage guidance, return value) and front-loaded with the primary purpose. While slightly verbose, every sentence adds value and 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?

Given the single parameter, rich annotations, and no output schema, the description covers purpose, behavioral traits, usage boundaries, and return type comprehensively. It fully informs the agent about what the tool does and when to use 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?

With 100% schema coverage, baseline is 3. The description adds meaning by explaining the parameter is used to find test infrastructure in the named package, specifically targeting test files, which goes beyond the schema description of 'package path or name'.

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 finds test helper structs and factory/builder functions in *_test.go files for a named package. It distinguishes from sibling tools like gograph_tests and filesystem search, making the purpose specific and 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, guiding the agent to use it before writing tests to avoid duplication, and not for test functions or external test data files. This provides clear context for 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?

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?

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds that the server checks freshness and may retry CHA/SSA after source changes, and explicitly states '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 structured with sections and front-loaded key info, but is slightly verbose with multiple paragraphs. However, every sentence adds value, so it earns a 4.

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 required param, no output schema, and comprehensive annotations, the description fully covers what the tool returns (files, symbols, edges, imports) and edge cases (empty when not found), making it complete for its 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 100% for one parameter 'package'. The description adds a concrete example ('internal/auth') and clarifies it can be a path or name, adding slight value beyond the schema 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 explicitly states 'Extract a comprehensive structural summary of one Go package' with specific deliverables: files, symbols, call edges, imports. It distinguishes from siblings by contrasting with single-symbol tools (gograph_context, gograph_source) and global search (gograph_query).

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

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

Includes explicit 'WHEN TO USE' and 'NOT TO USE' sections, giving clear context for orientation before editing and exclusions for symbol-level or global queries, with named 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, destructiveHint, openWorldHint. The description adds context about freshness checks and retry behavior for precise modes, which 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 clear sections but is slightly verbose due to multiple paragraphs. It is front-loaded with the core purpose and efficient overall.

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 one parameter, no output schema, and rich annotations, the description covers purpose, use cases, behavioral details, and return value expectations completely.

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 a clear description for the 'package' parameter. The description does not add meaningful semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'find' and the resource 'package-level variable declarations and the functions that mutate them'. It differentiates from siblings by explicitly excluding local-scope variables and environment variable reads, directing users to gograph_envs.

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 (auditing mutable global state, thread-safety hazards, shared singleton variables) and NOT TO USE (local-scope variables, env var reads) sections, providing clear guidance on 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=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?

The description discloses behavioral traits beyond annotations: freshness checking, retry behavior in precise modes, and explicitly states 'Read-only; no side effects'. Annotations already provide readOnlyHint and idempotentHint, but the description adds meaningful context.

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 (WHEN TO USE, NOT TO USE, RETURNS) and is front-loaded with the main functionality. It is slightly verbose in the freshness detail but each 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?

Given the tool's simplicity (one optional parameter, no output schema), the description provides complete context: purpose, usage guidelines, behavioral details, and return value description. It adequately prepares the agent to select and invoke 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?

The input schema has 100% coverage with a description for the 'term' parameter. The description in the tool text adds value by providing concrete examples ('e.g., 'POST' or 'api.example.com''), which goes beyond the schema 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 clearly states the tool's purpose: 'Find all outbound HTTP client calls detected in the codebase via net/http package-level functions'. It specifies the verb, resource, and scope, and distinguishes from sibling tool gograph_routes (HTTP server routes).

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 explicitly provide usage context. It suggests using the tool for auditing external API dependencies and identifying outbound HTTP traffic, and explicitly says not to use it for HTTP server route definitions (use gograph_routes).

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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context by noting 'The MCP server checks freshness before the call' and describing return behavior including 'count:0 JSON when no changed symbols exist.' This goes beyond the annotations, though it doesn't cover all possible edge cases (e.g., rate limits).

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

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

Every sentence earns its place. The description is front-loaded with the primary purpose, then structures modes, usage guidance, and return behavior with clear labels (WHEN TO USE, NOT TO USE, RETURNS). It provides substantive information without 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?

The tool has no output schema, so the description must explain return values—and it does: 'Transitive upstream affected symbols; with mermaid=true, Mermaid flowchart text; count:0 JSON when no changed symbols exist.' It also explains freshness checking and differentiates from a sibling, making the description complete for 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 100%, so schema descriptions carry the load for parameter formats. The description adds value by mapping parameters to usage modes: 'single symbol via symbol; uncommitted changes via uncommitted=true; git-ref changes via since.' This explains when each parameter is relevant, which is not fully captured in the schema.

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

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

The description opens with a specific verb and resource: 'Traverse the call graph backwards to find every symbol that transitively calls the target — the full upstream blast radius of a change.' It clearly distinguishes from siblings by explicitly saying NOT to use for direct one-hop callers (use gograph_callers).

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 explicit: 'Before refactoring a core function to see what breaks.' NOT TO USE is also explicit: 'For direct one-hop callers only (use gograph_callers).' The three modes (symbol, uncommitted, since) further clarify when each parameter is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining server-side refresh behavior: 'checks freshness... refreshes in current analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes.' This contextualizes behavior beyond standard 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 logical sections: core purpose, technical detail, usage guidelines, return format. It is front-loaded with the main action. While slightly lengthy, every sentence provides value and there is 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?

For a tool with 2 parameters, rich annotations, and no output schema, the description adequately covers key aspects: refresh behavior, return format ('List of implementing struct names with package paths and file locations; empty when no struct implements'), and parameter semantics. It is complete enough for effective agent use.

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

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

Schema coverage is 100% with both parameters documented. The description enhances the 'test_only' parameter by explaining its purpose: 'restrict to structs in *_test.go files (mocks/stubs).' This adds specific usage context beyond the schema's generic 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 clearly states the tool's purpose: 'Find all concrete structs that implement a named Go interface via duck-typing.' It specifies a precise verb (Find), resource (concrete structs implementing an interface), and method (duck-typing). It also differentiates from siblings like gograph_interfaces and gograph_fields.

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, listing use cases (polymorphism tracing, DI points, mock finding) and alternatives (gograph_interfaces for inverse direction, gograph_fields for struct fields). This guidance is precise and actionable.

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

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

Annotations already declare read-only and idempotent, but the description adds significant behavioral context: the MCP server checks freshness before the call, refreshes in the current analysis mode, and precise/precise_fallback graphs retry CHA/SSA after source changes. It also states 'Read-only; no side effects' and describes empty return semantics, going 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 front-loaded with the main purpose in the first sentence. Subsequent sentences are logically grouped into behavior, read-only status, and clearly labeled WHEN/NOT TO USE/RETURNS sections. Every sentence earns its place, with zero 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?

Given one parameter with complete schema coverage and no output schema, the description compensates by explaining return values ('File paths and package names of all importers; empty when the package is imported nowhere'). It covers purpose, usage, behavior, and return semantics comprehensively for the tool's 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 100% with the parameter already described as 'The exact import path'. The description reinforces 'exact' but doesn't add new format, constraints, or examples beyond the schema. The short-name contrast in NOT TO USE is a usage guideline, not parameter semantics, so the description adds marginal value here.

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 'Find all files and packages in the codebase that import a specific package by its exact import path' – a specific verb ('Find') and resource ('files and packages that import a package'). The NOT TO USE section further distinguishes it from sibling tools like gograph_deps and gograph_dependents.

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 (isolating third-party library usage, tracing internal package consumption) and NOT TO USE with named alternatives (gograph_deps for outgoing imports, gograph_dependents for reverse lookup by short name). This leaves no ambiguity about when to select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about freshness checks, mode-dependent retry behavior (CHA/SSA after source changes), and reaffirms 'Read-only; no side effects', which aligns with annotations and adds value beyond 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 purpose first, then behavioral details, usage guidelines, and returns. It is informative without being overly verbose; however, it could be slightly more concise by merging the freshness check details into fewer sentences.

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

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

For a tool with one simple parameter and no output schema, the description covers all essential context: operation, input, usage guidance, behavioral details (freshness, retries), return values, and edge cases (empty result). It is comprehensive for its 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?

The sole parameter 'struct' has 100% schema description coverage. The description says 'Given a struct name' which is essentially the same as the schema's 'The name of the struct'. No additional semantic meaning beyond the schema is provided, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Find all Go interfaces satisfied by a named concrete struct'), the resource (struct), and explicitly distinguishes from the sibling tool gograph_implementers by calling itself the inverse.

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, giving concrete scenarios and naming alternative tools (gograph_implementers, gograph_node, gograph_public) for different tasks.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds meaningful behavioral details beyond them: freshness checks, mode-specific refreshing, and CHA/SSA retry behavior. It also discloses return semantics (empty when no sites). No contradiction with 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 (WHEN TO USE, NOT TO USE, RETURNS) and front-loaded purpose. Each sentence contributes value, and the formatting aids scanning. Though moderately long, the complexity of the tool justifies the length.

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 a single-parameter tool with no output schema, the description fully covers required information: what it returns (file paths and line numbers), empty-result behavior, and relevant execution context (freshness/refresh). Combined with the strong annotations and schema, the description is complete 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?

The input schema has 100% coverage, describing the single parameter as 'The name of the struct (e.g., 'User').' The description adds little beyond restating 'named Go struct' and the Foo{...} example, which does not materially enhance parameter understanding. Baseline 3 is appropriate when structured schema already fully documents the parameter.

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: 'Find every composite-literal initialization site for a named Go struct,' and clarifies the exact syntax pattern (Foo{...}). It also explicitly distinguishes itself from sibling tools by stating what it is NOT for (magic values via gograph_envs, factory functions via gograph_constructors), eliminating ambiguity.

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 guidance ('Before adding a required field to a struct') and NOT TO USE guidance with named alternative tools. This gives the agent clear decision rules for selecting this tool versus relevant siblings.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description reinforces read-only, no side effects, and adds details on server freshness checks and retry behavior for precise modes. No contradiction with 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?

Description is well-structured with clear sections but slightly verbose. Could be shortened without losing meaning, but overall efficient for the information conveyed.

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 one required parameter and no output schema, description explains return values (struct names with file locations, empty when no mocks). Covers behavioral context, freshness, and use cases 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?

Only one parameter 'interface' with schema description 'The name of the interface (e.g., 'AuthService')'. Schema coverage is 100%, so description adds minimal value beyond 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 clearly states it finds structs in test files implementing a named interface (test doubles, mocks, stubs). It explicitly distinguishes itself from gograph_implementers by noting equivalence with test_only=true and compatibility reason.

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 writing tests, want to find existing mock implementations) and NOT TO USE (for production implementers, use gograph_implementers; prefer gograph_implementers(test_only=true) for new code). Also explains freshness checks and refresh behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context beyond that, explaining the two analysis modes (precise graph vs. standard), what mutations are detected (++/+=, pointer-alias, etc.), and that it re-runs analysis after source edits, all while reaffirming read-only nature.

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

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

The description is well-structured with an opening sentence, then explanatory details, then usage guidance, and finally return info. Every sentence adds value, though it is slightly verbose. It is not overly long and is 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 read-only tool with no output schema, the description clearly states what is returned ('mutation locations and indirect mutator method names when applicable'). It also explains the two analysis modes and the refresh behavior, providing a complete picture for an agent to understand inputs, behavior, and outputs.

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 provides a description for the single 'field' parameter (e.g., 'Status'), but the description adds important context on how to use it: 'Use Type.Field to exclude same-named fields on unrelated types'. This goes beyond the schema's basic example, justifying a score above the baseline of 3.

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

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

The description clearly states the tool finds 'struct-field and package-global mutation sites' with a specific verb 'find' and resource 'mutation sites'. It distinguishes from siblings by excluding field declarations (gograph_fields) and whole-struct initialization (gograph_literals) in the NOT TO USE section.

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 diagnosing state changes or auditing mutability, and explicitly excludes use for field declarations or whole-struct initialization. It also advises using Type.Field to avoid false positives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: the server checks freshness before the call, refreshes in the current analysis mode, and precise graphs retry CHA/SSA after source changes. It confirms read-only and no side effects, aligning with 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 concise (6 sentences) and well-structured with clear sections: main purpose, caching behavior, usage guidelines, and return information. Every sentence adds value and 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?

Given the simple schema (one parameter with good description) and rich annotations, the description provides a complete picture: what the tool does, when to use it (including alternatives), behavioral details (caching, freshness), and return values (array with kind, file, line, signature; empty if not found). No 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 single required parameter 'name' is fully described in the schema with an explanation and examples. The description does not add additional semantic 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?

The description clearly states the verb 'Fetch' and the resource 'AST metadata for a named symbol, package, or file'. It distinguishes from siblings by noting it is 'lighter than gograph_source for metadata-only lookups' and lists the specific metadata attributes (kind, file path, line number, etc.).

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, giving clear context for when to prefer this tool over alternatives like gograph_source for full source code and gograph_callers/gograph_callees for 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?

Exceeds annotations by describing full BFS reachability, freshness checks, retry behavior for precise graphs, and confirms no side effects. No contradiction with readOnlyHint or idempotentHint.

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?

Concise, well-structured, front-loaded with purpose, and every sentence adds value. Uses clear sections (WHEN TO USE, NOT TO USE, RETURNS).

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

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

Given zero parameters and no output schema, the description fully covers behavior, use cases, and return value format. Annotations cover safety profile; description adds algorithmic and refresh context.

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?

Input schema has zero parameters, so no parameter documentation needed. Description appropriately focuses on tool behavior rather than missing parameters.

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 explicitly states 'Find functions and methods unreachable from runtime roots' with specific scoping (main/init, tests, HTTP routes, exports) and method (BFS reachability). Distinguishes from sibling tools like gograph_usages and gograph_callers.

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' (code cleanup, dead-code audits) and 'NOT TO USE' (checking single symbol's usages, with alternatives 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?

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds valuable context about the MCP server refreshing source analysis before the call, which is a non-obvious side effect (e.g., performance or freshness implications). It doesn't contradict annotations and augments 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 appropriately sized, front-loaded with the primary action, and every sentence earns its place. It uses clear labels (WHEN TO USE, NOT TO USE, RETURNS) to organize information without wasted words.

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 relatively simple tool with no output schema, the description provides a complete picture: purpose, refresh behavior, read-only safety, usage guidance, alternative tool, and return format. It covers all essential aspects an agent needs to select and 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?

Schema coverage is 100% with clear descriptions for from, to, and mermaid. The description adds meaning by explaining the effect of mermaid=true and clarifying the structured return fields (from, to, found, steps[]), which helps the agent understand the tool's contract beyond the bare parameter names.

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: 'Find the shortest BFS call chain from one symbol to another.' This clearly distinguishes the tool from siblings by focusing on pathfinding between two symbols, and explicitly contrasts with gograph_impact for transitive upstream reachability.

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 ('To confirm reachability between non-adjacent symbols') and when-not-to-use guidance ('For all transitive upstream callers') with a named alternative (gograph_impact). This fully addresses usage 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 indicate read-only, idempotent, no side effects. The description goes further by noting that precise and precise_fallback graphs retry after source changes, and that the MCP server checks freshness before calling. No contradictions.

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, freshness/retry note, parameter explanation, usage guidelines, and return format. It is slightly long but earns its length by providing necessary detail without 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?

Given the tool's complexity (multi-planning for refactoring), the description covers inputs, behavioral details, usage guidance, and outlines the return JSON structure (inspect_first[], tests[], routes[], env[], risk, and optional inspect_contexts[]). No output schema, but the description compensates 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%, so baseline 3. The description adds value by explaining the purpose of each parameter: symbol (short name, dot-notation, fully-qualified), uncommitted (global plan for all uncommitted changes), and with_context (inline full source, callers, callees to avoid follow-up calls).

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 generates a structured pre-edit plan for a target symbol, listing specific outputs (symbols to read, tests, routes, env vars, risk). It distinguishes from siblings by mentioning that it is for upfront planning, while gograph_review is for post-edit verification.

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. It recommends using for multi-file refactoring and not for trivial single-line fixes, and names gograph_review as an alternative for post-edit verification.

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/destructive-hints, and the description aligns with 'Read-only; no side effects.' It further discloses freshness-check/refresh behavior and CHA/SSA retry logic, which adds value beyond the annotations. No 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?

Structured with a purpose sentence, behavioral note, WHEN/NOT sections, and RETURNS. Every sentence provides necessary guidance; it is front-loaded with the core function and uses formatting to aid scanning without being bloated.

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

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

The description fully compensates for the lack of an output schema by specifying the return shape (names, kinds, file locations) and edge cases (empty when no exports/not found). Combined with strong annotations and clear usage guidance, the context is complete for this read-only listing 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% for the sole 'package' parameter, so the schema already defines it. The description's mention of 'specific package' adds no new semantic detail beyond what is already in the structured 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 starts with a specific verb+resource: 'List all exported (public) symbols of a specific package' and enumerates the categories (functions, methods, types/interfaces, variables, constants). It clearly distinguishes this from siblings like gograph_node or gograph_api through the public scope and purpose.

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, naming exact alternatives (gograph_node, gograph_focus for private symbols; gograph_api for API drift). This leaves no ambiguity about when to select this tool over its siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that server refreshes source analysis before call and confirms no side effects, no contradictions.

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?

Concise, front-loaded with main action, then usage guidelines and return info. Every sentence is necessary and informative.

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 no output schema, description adequately specifies return type (matching symbols, files, imports) and empty result. Also mentions source analysis refresh. Complete for a search 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 has 100% coverage with descriptions for term and terms. Description adds OR semantics explanation and CLI equivalence, providing value 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?

Clearly states it searches the graph index for symbols, packages, files, and import edges using keyword substrings. Distinguishes from siblings like gograph_source and gograph_deps by specifying 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?

Explicit WHEN TO USE (initial exploration with keyword) and NOT TO USE (exact symbol or dependency trees) with specific sibling tool names. Provides clear context.

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

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

The description states 'Read-only; no side effects' and mentions freshness checks and retry behavior. This adds context beyond the annotations which already include readOnlyHint=true, idempotentHint=true, and destructiveHint=false. No contradiction with 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, but it is somewhat verbose. Every sentence adds value, so it earns a 4 for being appropriately sized and 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 covers when to use, not to use, behavioral details, and return value categories. Despite lacking an output schema, the description fully explains what the tool returns. It is complete for the complexity of the 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% with the single parameter 'function' well-described in the schema. The tool description does not add further detail about the parameter itself, but it explains the output classification. According to guidelines, baseline is 3 for high schema coverage, even without additional param info.

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

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

The description clearly states the tool's purpose: 'Show how each caller uses the return value(s) of a named function: discarded, assigned, partially ignored, returned upstream, or passed directly to another call.' It distinguishes from sibling tools like gograph_callers and gograph_errorflow.

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 guidelines: 'WHEN TO USE: Before changing a function's return signature... NOT TO USE: For error propagation tracing (use gograph_errorflow); for finding all callers without usage detail (use gograph_callers).' This helps the agent decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: freshness checking, refresh in current mode, retry behavior for precise graphs, and explicit 'Read-only; no side effects.' This complements 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?

The description is well-structured with sections and front-loads the purpose. While detailed, every sentence serves a purpose; it is concise for the complexity but slightly verbose with technical retry details. Minor improvement possible.

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 fully details the return JSON structure (changed_symbols[], tests[], routes[], etc.) and risk object fields. This gives the agent complete understanding of what the tool returns, making it highly 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%, but the description adds value by stating 'Requires either symbol or uncommitted=true,' clarifying mutual exclusivity/constraint beyond the schema's optional fields. This improves usability.

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

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

The description clearly states the tool's purpose: summarizing the scope and risk profile of a change, including symbols, tests, routes, env vars, and SQL involvement. It distinguishes itself from siblings like gograph_boundaries and gograph_plan by specifying what it does and does not do.

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' (post-edit verification) and 'NOT TO USE' (boundary enforcement or pre-edit planning) with alternative tool names (gograph_boundaries, gograph_plan). This gives clear guidance on appropriate contexts.

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 (readOnlyHint, destructiveHint, idempotentHint), the description adds that the tool combines multiple metrics, returns normalized scores and verdicts, mentions server freshness checks, and retry behavior. It explicitly declares 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 well-structured with a clear main sentence, followed by details and usage sections. While slightly lengthy, each sentence adds information and 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?

Given the complexity of the tool (multi-metric evaluation) and absence of an output schema, the description adequately describes the return structure (results with risk scores, verdicts, breakdown metrics) and distinguishes from relevant siblings. It covers all necessary aspects.

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 clear parameter descriptions. The description adds value by highlighting the mutual exclusivity requirement (either symbol or uncommitted=true), which is not obvious from the schema (both optional).

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 evaluates change risk profile for symbols or uncommitted changes, listing specific components (blast radius, cyclomatic complexity, etc.) and output format (normalized 0-100 score and verdict). It distinguishes from siblings by naming alternatives (gograph_review, gograph_plan) in the usage sections.

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 provide clear context and point to alternative tools. It also states the mutual exclusivity requirement (either symbol or uncommitted=true).

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 beyond the annotations by explaining internal caching behavior (content-digest freshness, AST refreshing) and limitations (unresolved dynamic prefixes). It also reaffirms read-only and no side effects, matching 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 sections for usage and returns, but includes some technical jargon (CHA/SSA, precise_fallback) that may be unnecessary for typical users. It is slightly verbose but still focused.

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

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

Given the absence of parameters and output schema, the description covers the return format, intended use cases, and limitations. It provides sufficient context for an agent to decide when to use 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?

Since there are zero parameters, the baseline is 4. No parameter descriptions are needed, and the description correctly omits them.

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

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

The description clearly states the tool's function: listing all HTTP routes with methods, URL patterns, and handler names. It also distinguishes itself from gograph_endpoint, making the purpose specific and 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?

It explicitly states when to use (to get the complete API surface before diving into a specific route with gograph_endpoint) and when not to use (for full call chain analysis, which gograph_endpoint handles). This provides clear guidance for 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description explains the freshness/refresh mechanism and retry behavior for different analysis modes, adding valuable behavioral context.

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 concise (4 sentences) and well-structured with clear sections for purpose, usage guidance, and return value, front-loading the core functionality.

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 fully specifies return values (struct names, package paths, file locations) and handles the empty case. The tool is simple and the description covers all necessary context.

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 single required parameter 'table', and the description adds value by providing usage examples of struct tags and clarifying that the parameter is a table or schema name.

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

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

The description clearly states the tool's purpose: finding Go structs mapped to a database table via struct tags, with examples of tags like `db:` and `gorm:`. It explicitly distinguishes from siblings like `gograph_fields` and `gograph_query` in the NOT TO USE section.

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, giving clear scenarios and alternative sibling tools for non-applicable cases, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavior beyond annotations: strict Session ID validation, reading only repository-confined logs, no additional prerequisites, and a summary of return values. This enriches the agent's understanding without contradicting 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 compact and well-structured with explicit labels (WHEN TO USE, RETURNS). Every sentence contributes meaningful information, with 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?

For a simple tool with two optional parameters and no output schema, the description covers the purpose, usage context, behavioral guarantees, and returns. It is self-sufficient even without additional structured context.

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 the parameters. The description adds no parameter-specific semantics, but the baseline of 3 is appropriate given the high schema coverage.

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

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

The description states a specific verb ('Review and grade') and resource ('agent compliance' and 'tool success rates'), with explicit grading criteria (Plan rule, Review rule, Composability/Efficiency). This clearly distinguishes it from sibling session tools like gograph_session_create or gograph_session_cleanup.

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 context: 'WHEN TO USE: After ending a session to obtain compliance metrics and recommendations.' This clearly indicates the timing but does not explicitly name alternatives or when not to use, which would merit a 5.

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

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

Annotations already signal destructive and non-read-only behavior. The description adds useful context: active logs are preserved, linked repository paths are not followed, and it returns the number of deleted files. The redundant note that annotations mark it destructive is not additive but does not detract.

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 structured with WHEN TO USE and RETURNS sections, making it easily parseable. However, the sentence 'MCP annotations mark this operation mutating and destructive' is redundant with the structured annotations, which slightly reduces conciseness.

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

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

The description fully explains what is deleted, conditional behavior (active log preserved), prerequisites, and return value. For a zero-parameter destructive tool, this is sufficient for safe invocation, though an explicit note on idempotence (already in annotations) could have made it a 5.

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 has zero parameters, so baseline is 4. The description appropriately notes 'No prerequisites', which clarifies that no arguments are needed and the call is unconditional aside from session state.

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 deletes 'stale inactive regular session telemetry JSONL logs' and scopes it 'without following linked repository paths'. It differentiates from sibling session tools (audit, create, end) by focusing on cleanup, so purpose is 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?

Provides clear usage context with 'WHEN TO USE: Call after auditing to keep the repository clean' and 'No prerequisites'. It gives a solid recommendation but does not explicitly discuss alternatives or when not to use, so it falls short of a 5.

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

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

Annotations already declare mutating and non-idempotent, and the description reinforces this while adding specifics: it writes only repository-confined state under .gograph/sessions and refuses linked storage. It also clarifies there are no prerequisites. This adds context beyond the 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?

The description is structured with labeled sections and front-loads the purpose. The sentence about 'MCP annotations mark it mutating and non-idempotent' is redundant since annotations are visible, but it doesn't significantly bloat the text. Overall, it earns its place.

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

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

For a single-parameter tool with no output schema, the description covers purpose, when to use/not use, side effects (write location and storage refusal), and return value (session ID). There are no gaps for the agent to select and 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?

The input schema already provides 100% coverage for the only parameter, custom_word, with a clear description. The tool description adds no parameter-specific guidance, but the schema fully compensates. 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 clearly states it 'Start[s] a telemetry audit session' for tracking compliance and success metrics, distinguishing it from sibling session tools like audit, cleanup, and end. It also specifies the resource scope (session state under .gograph/sessions), making it 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?

WHEN TO USE and NOT TO USE sections give explicit start-of-task and active-session conditions. It mentions no prerequisites once the MCP server is running, which is useful. However, it does not name alternative sibling tools (e.g., gograph_session_audit), so differentiation is less explicit than it could be.

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