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

With no annotations, the description carries the behavioral burden. It explicitly discloses the operation (executes the 14-phase pipeline), the scope (indexed Swift repository), and the return type (Markdown), which is strong disclosure for a read-only analysis tool. It doesn't mention latency or cost, but no side effects or auth concerns are implied.

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

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

Purpose is front-loaded in the first sentence, followed by a compact enumeration of the pipeline phases and a one-line return format. Every sentence contributes useful information and there is no filler.

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

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

The description is complete for a zero-parameter aggregate tool: it names all 14 analysis phases and the Markdown output format. It could add explicit guidance about when a single metric tool should be preferred, but this is a modest gap and the output schema likely covers return structure.

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 100% schema coverage, so the baseline is 4. The description correctly spends no space on parameters, and there is no missing parameter semantics to clarify.

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

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

States a specific verb and resource ('Run a full structural analysis of the indexed Swift repository') and enumerates the 14-phase pipeline, making the aggregate nature clear. It doesn't explicitly contrast with sibling tools like public_api or centrality, so it falls just short of full sibling differentiation.

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

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

The phrase 'full structural analysis' implies this is the umbrella tool for comprehensive results rather than individual metric tools, but no explicit when-to-use or when-not-to-use guidance is given. Alternatives like public_api or type_hierarchy are not mentioned, so the agent must infer routing from the phase list.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it computes a score with a specific formula, persists results to a 'centrality_scores' table, and returns a markdown table. It also notes the persistence side-effect. This is more than minimal, though it doesn't cover auth requirements or error conditions. No contradictions with annotations (none exist).

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: it states the purpose, explains the formula, mentions persistence, and lists params. It is dense but each sentence earns its place. The param documentation is at the end, which is conventional. No waste; it could be slightly trimmed but is appropriately sized for a tool with a formula and side effects.

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

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

Given the tool has an output schema (not shown in the prompt, but indicated as present), the description covers the return type ('Markdown-formatted ranking table'). It also explains the persistence and downstream use. It lacks edge-case handling or error scenarios, but for a centrality computation tool, the description is sufficiently complete for an agent to use it correctly.

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

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

The schema has no descriptions (0% coverage), but the description provides explicit parameter docs: ':param top: Number of top connectivity modules to return (default 20)' and ':param include_imports: Whether to include IMPORTS in connectivity (default True).' This adds meaning beyond the schema's types and defaults, fully compensating for the schema gap.

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

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

The description clearly states a specific verb and resource: 'Compute module connectivity: how many unique modules each module interacts with.' It then explains the score formula and the use case, and explicitly contrasts with betweenness centrality, which differentiates it from sibling tools like 'centrality'. The 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?

The description provides context on when to use it: 'For well-modularized codebases, identifies orchestrator and hub modules' and explicitly states it replaces betweenness centrality in cases where inter-module edges are zero. It also mentions integration with 'framework_nodes()'. However, it doesn't explicitly list alternative tools or when not to use it beyond the betweenness contrast, so it's clear but not exhaustive.

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

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

No annotations provided, so the description carries full burden. It explains stub resolution, cross-module callers, and rel flexibility. The return format is also disclosed. However, it doesn't mention potential performance costs, error behavior, or side effects (which are minimal). Slightly more detail on operational behavior would be ideal, but it is substantially transparent.

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

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

The description is moderately long but well-structured with clear sections: purpose, rel examples, workflow, params, and return. It avoids fluff and every sentence adds value. Slightly verbose but organized enough for efficient scanning.

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

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

Given the tool's complexity (multiple parameters, flexible relation types) and the absence of annotations, the description is remarkably complete. It covers the operation, usage context, parameter semantics, and result shape. An agent can confidently select and invoke this tool without further digging.

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 0%, so the description must compensate. It fully documents node_id, rel, and paths with concrete examples, defaults, and even describes the return format. There is no gap between the schema and the description; it covers everything the agent needs to invoke it correctly.

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

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

States a precise verb (return all nodes that call a given node) with a specific resource (node via sym: stubs). It also explicitly contrasts with query_codebase, making it easy for an agent to distinguish.

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 a clear when-to-use: a reverse lookup vs query_codebase's semantic expansion. Includes a workflow example and explains the rel parameter for non-CALLS relations. Explicitly covers alternatives and exclusions (e.g., paths to exclude tests).

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains determinism, relation-type edge weighting, cross-module amplification, the private-symbol penalty, score normalization, and the difference between node and module aggregation. This gives an agent a clear model of how the computation behaves beyond a simple 'rank nodes' statement.

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 definition, a compact algorithm paragraph, three use-case bullets, and parameter/return documentation. There is no filler, and the length is justified because the schema supplies no parameter descriptions.

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

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

Given three optional parameters, no annotations, and no schema descriptions, the description covers the algorithm, use cases, parameter semantics, and return format. It is self-contained enough for an agent to decide when to invoke it and how to set arguments 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 provides zero description coverage, so the description must fully explain the parameters. It documents top's default, kinds' accepted values and empty-string behavior, and group_by's two modes with their output differences. It also notes that kinds is ignored when group_by='module', which is exactly the kind of semantic detail an agent needs.

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 operation ('Compute Structural Importance Ranking (SIR) for the indexed codebase') and specifies the algorithm ('deterministic weighted PageRank over the sym-stub-resolved call graph'). It identifies the resource and output type, but it does not explicitly contrast itself with sibling ranking tools such as rank_nodes or query_ranked, so differentiation is implicit rather than explicit.

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?

A dedicated 'Use this to' section provides three concrete use cases: identifying critical symbols, understanding depended-on modules, and prioritizing review/refactoring/test efforts. However, it does not state when not to use this tool or name alternative sibling tools, so exclusions and comparisons are absent.

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

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

No annotations are provided, so the description carries the full burden. It clearly describes the output format (markdown, LLM-ready), the included sections, and how limit behaves. It does not explicitly state read-only/no side effects, but the described behavior strongly implies a pure retrieval operation.

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 front-loads the core purpose and uses a bullet list for the return sections. Every bullet adds value, and the param/return lines mirror typical docstrings without redundancy. A couple of sentences could be tightened, 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?

Given the simple input schema and existing output-schema coverage, the description is nearly complete: it explains the use case, both parameters, and the output content. It omits only error behavior for invalid node IDs, which is minor for this tool class and not a blocker for correct invocation.

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

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

Schema description coverage is 0%, but the description fully compensates: node_id is explained with a concrete example and format, and limit is defined with both its default and the special 0 value. This is exactly the semantic content an agent needs beyond the bare 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 states a specific verb ('Return a natural-language explanation') and a specific resource ('a code node'), and the bullet points differentiate it from callers/get_node by showing it aggregates kind, location, call graph, and documentation. The example node ID makes the scope concrete.

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

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

It explicitly says this is ideal for understanding a node's role and context without reading source, and it names pack_snippets() as the follow-up tool to retrieve implementation. It does not explicitly mention alternatives like callers or get_node for narrower queries, but enough guidance is present to route an agent.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It states that it 'returns a Markdown report' and describes the conditions under which semantic information is included, which implies a read-only query. However, it does not explicitly state that the tool has no side effects, nor does it mention error handling, prerequisites, or limitations. It is transparent enough for a non-mutating tool, but could be more explicit.

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 and well-structured. It opens with the primary purpose, then details the report contents, and finally explains parameters and return format. Every sentence contributes value, and the layout is front-loaded with the most important 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?

Despite having an output schema (not shown), the description enumerates the report's components in detail: structural position, call counts, importers, inheritance, global score, and optional semantic relevance and proximity. Combined with thorough parameter explanations, an agent has everything needed to invoke the tool correctly and understand its output. The description is complete for this 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 description coverage is 0%, so the description must explain parameters fully. It does: node_id is described with a concrete example of a stable node identifier, and q is explained as an optional query that controls whether semantic score and proximity are included. This adds significant meaning beyond the bare schema and fully compensates for the lack of 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 clearly states the tool explains CodeRank score components for a specific node, and lists the specific content of the report (callers, importers, inheritance, score, semantic relevance). This is a specific verb+resource and distinct from sibling tools like 'rank_nodes' or 'query_ranked', though it does not explicitly name them.

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

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

There is no guidance on when to use this tool versus alternatives. It describes the tool's behavior but never mentions when to prefer it over siblings like 'rank_nodes' or 'query_ranked', nor any exclusion conditions. The only conditional is about the 'q' parameter, which is not about 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the matching logic (innermost node by line range), fallback to module, automatic stripping of './', and the return type (Markdown or error). This adds value beyond just saying 'finds a definition' and gives the agent clear expectations.

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 lengthy but every sentence contributes—purpose, usage context, matching algorithm, param details, and return behavior. It is well-structured with a clear opening and organized param list. Slight verbosity in the fallback explanation could be trimmed, but overall it is efficient 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?

For a tool with 2 parameters and no output schema shown, the description explains everything an agent needs: the exact input format with an example, the line indexing, the matching rules, fallback behavior, and the return format. There are no obvious gaps that would prevent correct invocation.

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

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

Schema description coverage is 0%, so the description must fully explain both parameters. It does: 'file' is described as 'Module path as stored in the graph, e.g., Sources/Networking/Client.swift' with the note about leading './' stripping, and 'line' is 'Line number (1-indexed) within the file.' This is comprehensive and compensates entirely for the lack of 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 states a specific verb and resource: 'Find the code node whose definition spans a given file location.' It clarifies it reverse-resolves a (file, line) pair to a node ID and returns the same report as 'explain()'. This clearly distinguishes it from siblings like get_node or find_node, which operate on node IDs or names.

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 use case: 'Useful when reading a file in an IDE and wanting to understand the symbol at a specific line without constructing a node ID manually.' It implies when to use it over alternatives (e.g., when you lack a node ID) and notes the fallback to module node. It doesn't explicitly state when not to use it, but the guidance is sufficient.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does not explicitly state that it is a read-only operation, but the description 'Find graph nodes' implies a query. It mentions case-insensitive matching, which is a behavioral trait. But it lacks information about potential errors (e.g., if no match found) or pagination. Given no annotations, the description provides some but not comprehensive 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: 3 short paragraphs. It opens with the core purpose, then gives usage context笑容, then param docs. The sphinx-style parameter docs are structured and clear. Every sentence adds value; no 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?

The tool has 2 params (1 required), a simple purpose, and an output schema for return structure. The description covers what the tool does, when to use it, and explains both parameters. It does not detail return values, but an output schema exists, so that is not necessary. For a simple lookup tool, this is sufficient. Could mention case-insensitivity as a behavior, but that is disclosed. Only minor gaps like error behavior, so a 4 out of 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?

Schema description coverage is 0%, so the description must compensate. It does: it explicitly explains the 'name' parameter as 'Function, type, or protocol name to search for' and 'kind' as 'Optional kind filter: module | class | struct | protocol | function | method | etc.' This adds meaning beyond the bare schema, which only lists names and types. The description adds the enum-like values for kind, which is helpful.

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 graph nodes by name, specifically without needing the full stable ID. It distinguishes itself from sibling tools like get_node by focusing on name-based lookup. The description also mentions matching against name and qualname, giving specific resource types.

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

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

It provides clear context: 'Use when you know a function or class name from reading code and need its stable ID.' This helps an agent decide when to use this tool, though it doesn't explicitly mention when not to use it or alternative tools. However, the purpose is clear enough to avoid confusion with siblings like get_node.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the scoring formula, notes that values are auto-computed on first call (implying potential caching), and describes the output format as a Markdown table. This is transparent about computation and return type, though it doesn't mention side effects or data freshness.

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 a clear opening line, a definition, the formula, and a return note. It's front-loaded with the core purpose and avoids unnecessary fluff. It's slightly longer than strictly necessary, but each sentence contributes meaningful 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 the tool's simplicity (one parameter) and the presence of an output schema, the description is fairly complete. It explains the algorithm, output format, and performance note about auto-computation. It doesn't cover edge cases or usage examples, but for this tool, the essentials are covered.

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 `top` is explicitly explained in the description with its purpose and default value. Even though the schema itself has no description, the tool description provides full semantic meaning, going beyond what the schema alone offers. This fully compensates for the 0% schema description 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's purpose: identifying framework-like (hub) modules using SIR and connectivity. It defines what a framework node is and provides a specific scoring formula. While it doesn't explicitly differentiate from siblings like centrality or rank_nodes, the unique combination of SIR and connectivity makes it distinct.

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 implies when to use the tool (when you need to find architecturally central and highly connected hub modules) but does not explicitly mention alternatives or when not to use it. It provides context about high-scoring modules being critical hubs, but lacks exclusionary guidance compared to sibling 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?

With no annotations, the description explains the stable ID format, the Markdown output, and the meaning of include_edges. It stops short of describing error/not-found behavior, but core runtime behavior is clear.

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

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

The purpose is front-loaded in the first sentence, followed by a compact ID pattern and clear parameter docs. No vague filler or redundant restating.

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 essential details for calling the tool are present: parameters, ID format, output form, and edge behavior. The only missing context is explicit routing guidance among sibling tools.

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?

Even though schema coverage is 0%, the description fully documents both parameters: node_id with a concrete pattern and examples, and include_edges with its effect. This adds substantial meaning beyond the bare schema.

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

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

States a precise action: fetch a single Swift node by stable ID and render as Markdown. The ID pattern and examples further distinguish it from listing or searching 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 intended use is implied: when you have a stable node ID and need one node as Markdown. It does not explicitly compare against siblings like find_node, list_nodes, or query_codebase.

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

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

No annotations are present, so the description carries the burden of disclosure. It accurately frames the tool as a non-mutating reporting operation, describes the Markdown return format, and specifies doc-comment coverage calculation. It does not discuss performance or prerequisites, but for a zero-parameter stats tool this is sufficient.

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: a one-line purpose, a usage trigger, a useful coverage detail, and a precise return description. No filler or duplication exists.

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 annotations and an output schema present, the description covers purpose, output format, and when to call it. It could be slightly stronger by noting any required repository preparation or when to prefer sibling tools, but nothing essential 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?

The tool has no parameters and schema coverage is 100% (empty schema), so the baseline is 4. The description adds context about what the current repo's stats will include, which is helpful despite no parameter documentation being needed.

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

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

The description names a specific operation and output: returning node/edge counts by kind and relation, plus doc-comment coverage. This clearly distinguishes graph_stats from sibling tools like get_node, list_nodes, and type_hierarchy, which target different granularity.

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

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

It explicitly says to call this tool first when engaging with a new Swift repo, giving clear contextual guidance. It does not name alternative tools or state when not to use it, so it stops short of a full when/when-not routing.

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

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

No annotations are present, so the description must carry the transparency burden. It discloses the filtering semantics (prefix and/or kind) and the return format (JSON array of node dicts); it does not mention pagination or empty-filter behavior, but for a read-only list these are secondary.

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?

Starts with a one-sentence summary, then pair of :param lines and a :return line. No filler; the kind enumeration is the only length, and it is necessary for correct use.

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 an output schema present, return values are already covered; the description adds the filter behavior and parameter details that the schema lacks. It is complete enough for successful invocation, though it could note whether empty filters return all nodes.

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 no descriptions and 0% coverage, so the description fully compensates. It defines module_path as a prefix filter with a concrete example and enumerates all valid kind values.

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

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

States a precise action ('List nodes') and the two filter axes (module path prefix and kind). This is enough to distinguish it from sibling tools like get_node or find_node, though it does not name them explicitly.

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

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

Implies use for retrieving a filtered set of nodes rather than a single node or a free-text query, but never explicitly contrasts it with siblings or states when to prefer it. No prerequisites or exclusions are provided.

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

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

With no annotations, the description carries the burden, and it does disclose the key behavior: it returns a Markdown string, performs hybrid ranking, deduplicates snippets, and grounds them in source with line numbers. It does not explicitly state read-only/no side effects, but 'Returns' and 'extraction' strongly imply a non-mutating query.

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 summary is front-loaded and each param line is compact and information-dense; no sentence is wasted. For a 12-parameter tool, this is appropriately sized and well structured.

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 high complexity and no annotations, the description covers what the tool returns, how the query/rerank process works, and every tunable parameter. An agent has enough information to invoke it correctly without opening schemas or sibling definitions.

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 0%, so the tool would be opaque without param docs; the description compensates fully by explaining all 12 parameters, including defaults, valid choices for rerank_mode, the [0,1] range for min_score, and the 0-disables behavior for max_per_module.

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

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

The opening line identifies a specific operation: hybrid query and source-grounded Swift snippet extraction, and the next sentence specifies the exact output (Markdown context pack of ranked, deduplicated snippets with line numbers). This clearly distinguishes it from sibling graph-query tools such as query_codebase or get_node.

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 phrase 'ready for direct LLM ingestion' gives a clear use case for choosing this tool, and the parameter list implies it is for rich, graph-expanded snippet retrieval. It does not explicitly name alternatives or state when not to use it, 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains that the result is a fact read from the graph, not a heuristic, and describes the return shape (count and declarations with visibility). It doesn't mention performance, rate limits, or edge cases, but for a read-only listing tool this is solid.

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 clear first sentence, a rationale sentence, two use cases, and then parameter documentation. Every sentence earns its place, and the key purpose 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 tool has an output schema, so return values are already structured. The description adds the key context: it's a graph fact, not a heuristic, and it covers the two parameters. It could mention whether the result is sorted or how visibility is represented, but it's complete enough for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains module_path restricts to files under a path prefix and that empty covers the whole repository, and limit caps the number of declarations (1-1000). This adds meaning beyond the raw 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 states a specific verb ('List') and resource ('declared public API surface'), and explains what the tool does: it reads a fact out of the graph rather than using a heuristic. It clearly distinguishes itself from siblings like query_codebase or find_node by focusing on public API declarations and their visibility.

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

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

The description gives clear use cases: 'review what a module actually exposes' and 'find public declarations that no longer need to be.' It doesn't explicitly name alternatives or say when not to use it, but the context is strong enough for an agent to select it appropriately among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses the hybrid semantic+structural approach, graph expansion behavior, rerank modes, and output format, which goes beyond the schema. It does not mention side effects or auth, but the tool is clearly a read-style query operation.

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 summary line is front-loaded and the parameter list is systematically formatted. It is somewhat long, but given 11 parameters, each documented line earns its place. No irrelevant filler is present.

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 high parameter count and the presence of an output schema, the description is nearly complete: every parameter is explained and the return type is stated. It lacks examples and usage guidance relative to sibling tools, but an agent can invoke it correctly from the provided information.

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 0%, so the description must fully compensate. It documents all 11 parameters, including defaults, allowed values, and semantics for q, k, hop, rels, max_nodes, min_score, max_per_module, rerank modes, weights, and format. This is exemplary compensation for an empty schema.

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

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

States a specific action: hybrid semantic + structural query over the Swift codebase graph. This is clear and resource-specific, but it does not differentiate itself from closely related siblings like query_ranked or rank_nodes.

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 explains what the tool does and its parameters, but provides no guidance on when to choose it over sibling tools. With many related query/ranking tools present, explicit alternatives or selection criteria are missing.

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

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

With no annotations provided, the description carries the full burden, and it does well: it discloses the combination formula, mode weights, that 'sym:' import stub nodes are always excluded, and that output is a JSON array with score components and 'why' strings. It does not explicitly state read-only behavior, but 'query' plus the detailed output contract makes behavioral expectations reasonably transparent.

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 front-loaded: the first sentence states the tool's purpose, the mode formulas add precise algorithmic context, and the parameter list is compact and informative. Every sentence contributes meaningful information without unnecessary 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 tool with 7 parameters, no annotations, and an output schema, the description is remarkably complete: it explains the algorithm, mode weighting, parameter meanings, return format, and output exclusions. An agent has enough information to invoke the tool correctly and interpret its results.

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

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

Schema description coverage is 0%, so the description fully compensates by documenting every parameter: q, k, mode, top, rels, radius, and exclude_tests, including defaults and semantic meaning. It also clarifies mode choices and the rels format beyond what the bare schema provides.

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

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

The description states a specific action ('Rank query results') and resource ('using CodeRank-enhanced hybrid or personalized PageRank'), making the tool's core purpose immediately clear. It gives algorithmic detail and modes, but does not explicitly contrast it with sibling tools like rank_nodes or explain_rank, so it lacks explicit sibling differentiation.

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

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

The description implies usage for natural-language query ranking and explains when to choose 'hybrid' vs 'ppr' modes by giving default weights and semantics. However, it does not state when to prefer this tool over alternatives such as query_codebase, rank_nodes, or explain_rank, so usage guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It discloses the graph construction, default relation weights, test exclusion, and optional persistence behavior. It also explains the return fields. It does not mention side effects of persistence (e.g., overwriting existing metric names) or performance implications, but the disclosed behavior is substantial and transparent.

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 summary paragraph followed by parameter documentation. It is slightly verbose but every sentence adds value, including the algorithm details and persistence behavior. The front-loaded summary gives the agent the core purpose immediately.

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 (graph algorithm, multiple parameters, optional persistence, rich output), the description is quite complete. It covers inputs, defaults, behavior, and return schema. It lacks explicit notes on persistence side effects or performance, but the output schema and parameter docs cover most of what an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: each parameter (top, rels, persist_metric, exclude_tests) is explained with defaults and examples. The return format is also documented. The only minor gap is that 'rels' format is described as comma-separated but valid relation names are not enumerated beyond the default list.

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 computes global weighted CodeRank (PageRank) over the repository graph, with a specific verb ('Compute') and resource ('repository graph'). It distinguishes itself from siblings like centrality and bridge_centrality by specifying the weighted PageRank algorithm and default relation weights. The scope is precise and actionable.

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 explains when to use the tool: to identify structurally important nodes via weighted PageRank, and notes test paths are excluded by default. It does not explicitly name alternatives or when-not-to-use conditions, but the context is clear enough for an agent to select it over siblings like centrality or bridge_centrality. A small gap is the lack of explicit comparison to query_ranked or explain_rank, which are likely related.

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

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

With no annotations, the description carries the full burden. It clearly discloses the return shape (metrics and issues for both sides, computed delta, node/edge count deltas) and the error-dict behavior for invalid keys. It does not explicitly state side effects or read-only guarantees, but the compare operation strongly implies 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 front-loaded with the core purpose, then gives return detailsholistically, then a minimal two-step workflow example. It is organized and dense without redundancy; every sentence adds operational 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?

Given a bare input schema and no annotations, the description provides enough context for an agent to call the tool correctly: how to obtain valid keys, what the delta means, exact top-level return keys, and error behavior. No essential operational context 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 has zero description coverage, but the description fully compensates: both key_a and key_b are explained as snapshot keys from snapshot_list() and typed as tree-hash strings. This is above-and-beyond schema-only information.

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 leads with a specific verb and resource: 'Compare two codebase metric snapshots side-by-side.' It also clarifies what the comparison yields (delta of node and edge counts, per-kind breakdowns), making the tool's purpose unmistakable even without opening the schema.

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

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

Provides a concrete workflow: call snapshot_list() to obtain keys, then snapshot_diff() using the key= fields. This tells the agent how to prepare inputs. It does not explicitly contrast with sibling tools like snapshot_show or snapshot_list, so it falls just short of full alternative-selection guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses the list-only nature, the reverse-chronological ordering, the included summary fields, and the deltas-vs-previous behavior. It does not mention edge cases (e.g., empty list, invalid branch), but the core reading behavior is clear.

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

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

Well-structured with an opening goal sentence, a result-detail paragraph, usage examples, and a param block. It is slightly long but every sentence adds distinct value; the only minor redundancy is restating 'codebase metrics' in the first and second 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 read-only list tool with two params alert and no annotations, the description covers ordering, fields in each entry, deltas, defaults, the 0-means-all behavior, and how the key links to sibling tools. The presence of an output schema reduces the need to document the return shape beyond what is given.

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 effectively 0% since the input schema only gives names and defaults. The description compensates fully by explaining both parameters: limit caps results and accepts 0 for all, branch filters by branch with an example. This is exactly the semantic meaning the schema lacks.

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?

Clearest possible statement: 'List saved temporal snapshots of codebase metrics in reverse chronological order.' It names the operation, the resource, and the ordering, and it distinguishes the list view from snapshot_show/snapshot_diff by describing the summary-level content.

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 gives example questions this tool answers and tells the user to pass the returned 'key' to snapshot_show or snapshot_diff, which strongly signals boundaries against sibling tools. It does not explicitly say 'if you need full snapshot content, use snapshot_show instead,' so it falls just short of a perfect 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?

No annotations are provided, so the description carries the full burden. It discloses the default behavior ('latest'), the return structure (metrics dict, hotspots, deltas), and error behavior (error dict if snapshot does not exist). This is strong behavioral disclosure for a read-only retrieval tool, though it doesn't mention performance or 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?

The description is well-structured and front-loaded with the core purpose. It uses a clear paragraph plus param/return documentation. It is slightly verbose in listing the full metrics dict, but that detail is useful for an agent deciding whether this tool returns what it needs.

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 has one optional parameter, an output schema, and no annotations, the description is nearly complete. It covers the parameter, the return value, and error behavior. It could mention that the output is a JSON object and that deltas are computed vs previous and baseline, which it does. Minor gap: it doesn't explicitly state that the tool is read-only, but that is implied by 'show' and the absence of mutation language.

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 0%, so the description must compensate. It does: it explains the 'key' parameter, its default value, the special 'latest' value, and that keys are tree hashes from snapshot_list. This fully covers the single parameter's 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 clearly states the tool's purpose: showing full details of a specific codebase metrics snapshot. It specifies the resource (snapshot), the action (show), and the key mechanism (snapshot key or 'latest'). It also distinguishes itself from siblings like snapshot_list and snapshot_diff by describing what it returns (full metrics, hotspots, deltas).

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 explains when to use this tool: to retrieve a specific snapshot by key or the latest one by default. It also tells the user where to get snapshot keys (from snapshot_list). It doesn't explicitly say when NOT to use it or name alternatives like snapshot_diff, but the context is clear enough for an agent to select it appropriately.

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?

Since no annotations are provided, the description carries the burden of behavioral disclosure. It accurately states the tool returns all relationship data without side effects (no mutation). It covers what the tool does and its return structure, but doesn't mention potential edge cases like missing node IDs or error behavior. Still, for a read-only query tool, the description is reasonably transparent.

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 one-sentence summary followed by explicit bullet points for each relationship, and then a practical note about the alternative method. The parameter documentation is included inline, and the whole text is front-loaded with the tool's purpose. No 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?

The tool has an output schema (though not detailed here), and the description fully explains the input parameter and the structure of the output, listing all six fields (node, conformers, subclasses, extensions, conforms_to, inherits_from). The only minor gap is not detailing the exact format of node_id beyond an example, but the example is fairly illustrative. Given the complexity of Swift's type system, the description provides nearly complete 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 input schema provides only the parameter name 'node_id' with no description. The description supplements this by specifying the node types (class, struct, etc.) and giving a concrete example ID format. However, it doesn't explain the exact format beyond the example, and the coverage is high for a single required param. Baseline 3 is appropriate as the description adds value but the schema is minimal.

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 the tool's purpose: returning all relationship facts for a Swift type. It explicitly enumerates the four relationship categories and explains the Swift-specific motivation for combining them. This differentiates it from siblings like callers and get_node, which would require multiple calls.

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

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

The description explicitly contrasts this tool with calling callers() three times, stating that this tool returns the same facts together, 'already labelled'. This gives clear when-to-use guidance and names the alternative approach. It also emphasizes the Swift-specific relevance, implying it's not needed for other languages.

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