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 states 'Read-only' and discloses that the response carries 'the alias set with path evidence,' which is useful behavioral context beyond the schema. It could add more edge-case or authorization detail, but the core behavior is 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?

Three concise sentences, all informative. 'Read-only' is front-loaded for safety, and the differentiating sibling relationships are stated without padding.

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

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

With no output schema and no annotations, the description still provides enough context: purpose, usage, relation to siblings, and a summary of the response contents. It could mention format-specific behavior or path-evidence semantics, but an agent can select and invoke the tool correctly with the given 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 100%, so the parameters are fully documented in the schema. The description adds minimal parameter-specific detail beyond referring to 'this one,' so it does not need to compensate for gaps.

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 clear verb and resource: 'Return the values that alias this one.' It also explicitly distinguishes the tool from siblings by contrasting it with `points_to` (objects a value points to) and `flow` (where a value goes), so an agent can tell them apart.

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

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

It gives an explicit use case: 'Use it to find every name for the same object before reasoning about a mutation.' It also names complementary alternatives, though it does not explicitly state when not to use this tool in favor of them.

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 behavioral burden. It leads with 'Read-only,' clearly states the deterministic graph-based computation, discloses that labels are graph-derived member names rather than generated prose, and explains the edge-count/hub output. This gives an agent an accurate model of the tool's behavior and 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?

Two compact sentences convey purpose, alternatives, pagination, and output semantics with zero filler. The read-only flag is front-loaded, and each phrase earns its place by either defining behavior or routing to sibling tools.

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

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

For a 6-parameter, all-optional, no-output-schema tool, the description provides sufficient context: what is mapped, how results are structured, how to navigate paging, and which sibling tools to use in related cases. The schema covers parameter defaults and limits, while the description covers the conceptual and operational context needed 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?

Schema description coverage is 100%, so the parameters are already fully documented. The description adds value beyond the schema by clarifying that all params are optional and by explicitly mapping `offset` to community pagination and `file_offset` to per-community file pagination. This contextual paging semantics goes beyond the schema's minimal wording.

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

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

The description clearly states a specific verb ('Map') with a precise resource (the codebase's architecture) and defines the output as deterministic file communities over the call + dependency graph with edge counts and hubs. It explicitly differentiates itself from sibling tools by naming `communities` and `hubs` as the function-level and central-function alternatives.

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

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

The description gives explicit guidance on when to use this tool: as a directory-independent 'what are the big pieces' view, and when to use alternatives: `communities` for function-level subsystems and `hubs` for central functions. It also provides concrete invocation guidance with pagination semantics for `offset` and `file_offset`.

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 full burden. It thoroughly discloses caching behavior (content-addressed, instant for unchanged trees), refresh semantics, loading of the graph on success, toolchain prerequisites (node, clang) with actionable errors, and performance caveats (in-process, can take minutes, timeout). This is exceptionally 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: purpose first, then caching, loading, toolchain, and performance. Each sentence adds value with no fluff, though it is somewhat lengthy at ~150 words. Overall effective 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?

Covers purpose, usage context, prerequisites, caching, performance, and timeout. Missing explicit description of the return value/content (since no output schema exists), but the side effect of loading the graph for subsequent calls is described. Slight gap on what text/json output contains, but overall complete for the tool's primary function.

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

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

Schema coverage is 100%, so each parameter is already documented in the schema. The description adds context on timeout semantics (can take minutes, default 300) and refresh meaning, but doesn't introduce significant new meaning beyond the schema. Baseline 3 is appropriate given 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 (build) and resource (Lachesis graph from source directory), and clearly differentiates from siblings by calling it the zero-config way to start on a repo with no graph yet, with no separate build step needed. This distinguishes it from load_graph and other analysis tools.

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

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

Provides explicit context: use when starting on a repo with no graph yet, and includes guidance on handling long builds (smaller subtree or out-of-band lachesis build). While it doesn't name alternatives like load_graph directly, the use case is clear enough for an agent to select the right 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?

With no annotations, the description carries the burden, and it does a good job: it discloses that direct and indirect calls appear as tagged rows, explains the meaning of resolved:false, and clarifies the in-repo limitation. It also tells the agent exactly what direct_only changes about the result set.

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

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

The description is compact and front-loaded; the most useful information appears first. The final 'A jump move' line adds marginal color but is not harmful, and the rest of the text contains meaningful detail without padding.

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

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

The description gives enough for a first call, but with no output schema and no annotations it does not fully describe the result shape, text vs JSON differences, or how to interpret an `indirect(...)` tag beyond resolved:false. Some important context is left to inference, though the described behaviors cover the common use case.

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 only 20%, and the description compensates for direct_only but not for the other parameters. 'name' is implicitly identified by the opening sentence, while limit and offset are left to their obvious pagination meaning. The core parameter direct_only is well explained, so this is adequate but not complete.

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 resource (symbol), the operation (callees/calls), and the scope (in-repo only), and it distinguishes direct calls from indirect dispatch. This is enough to separate it from sibling tools like 'callers' 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?

It gives concrete guidance: set direct_only to get resolved declaration-only calls; otherwise indirect dispatch is included. It also states that rows represent in-repo calls only. It does not explicitly name alternatives, but the tool's relation to 'callers' and its direct/indirect distinction make the intended context clear enough.

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 behavioral burden, and it mostly succeeds: it discloses direct + indirect dispatch modes, the tagging scheme (direct | indirect(may_invoke|context|fn-pointer)), external stubbing filtering, and the effect of direct_only. It does not explain the output schema or rate limits, but for a read-oriented query tool the key behavioral contract is clearly given.

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, front-loaded with the core purpose, and each meaningful sentence adds behavior or scope. The final fragment 'A jump move' is unclear and does not earn its place, making the description slightly less polished than it could be.

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 reasonably tells the agent what rows look like (tagged by call kind) and how to narrow behavior using direct_only. It could be more explicit about the exact return field names, paging behavior, or syntax for passing a symbol name, but the stated details are enough for an agent to correctly invoke the tool and interpret results.

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

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

Schema description coverage is low (only format has a description), and the description adds meaning mainly to direct_only. The phrase 'Who calls this symbol' implicitly explains the required name parameter, and limit/offset are conventional with schema defaults; format is already described in the schema. This is adequate but not detailed, since direct_only-like semantics are not expanded for all fields.

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

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

The description opens with a concrete question, 'Who calls this symbol', and clarifies the exact scope: direct + indirect dispatch, with external stubs filtered. This differentiates it from sibling tools such as callees (which would be the reverse direction) and indirect_targets (which focuses on a narrower set of indirect resolution 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 tells the agent when to use the direct_only flag, saying it returns only resolved decl->decl calls, and it explains that external stubs are filtered by default. It does not explicitly name alternatives or exclusionary conditions, but the behavior contrast is strong enough for an agent to select between this and related caller/callee 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?

No annotations are provided, so the description must carry the full burden. It mentions 'explicit analysis frontiers' and 'exhaustive counts' but does not disclose that the tool has a temporal evaluation behavior, a hard stop that degrades results, or that it returns a `temporal_evaluated` flag. Since these are significant behavioral aspects (potential partial results, termination), the description is insufficient.

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

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

Two sentences with no fluff; the core function and a usage example are front-loaded. It is appropriately concise 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?

Given the four parameters, no output schema, and no annotations, the description gives a clear purpose but omits the temporal/hard-stop behavior that the parameters control, which is important for an agent to understand the tool's performance and degradation semantics. The schema partially covers this, but the description could tie it together. Overall it is adequate but not 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 75% with three parameters having descriptions; the only undocumented parameter is `constructor_id`. The tool description adds no information about parameters beyond what the schema already provides. Since coverage is high, the description does not need to compensate, but it also does not add value; baseline 3 is correct.

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

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

The description states a specific verb ('Report') and resource ('constructor metadata, exhaustive counts, and explicit analysis frontiers'), and gives a concrete use case ('distinguish an empty result from missing coverage'). It is clear and distinct from siblings like 'candidates' which likely list candidates. However, it does not explicitly name a specific alternative, so it is not a full 5.

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 scenario ('Use this to distinguish an empty result from missing coverage') but does not explicitly say when not to use it or name alternative tools. It gives context but no exclusions, so a 4 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?

With no annotations provided, the description must disclose behavioral traits. It states the content is a 'neutral evidence capsule' with 'observations and bounded inferences,' which clarifies the nature of the output but does not mention side effects, performance implications, or how the tool behaves under different parameter settings. The description also omits any discussion of the configurable options (format, temporal, hard_stop) that affect 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 a single, front-loaded sentence with no filler. It efficiently conveys the core purpose and the key distinction (no verdict). It is appropriately concise, though it could be slightly more informative without becoming verbose.

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 four parameters and no output schema or annotations, the description is quite sparse. It does not describe the structure of the 'evidence capsule,' the meaning of 'bounded inferences,' or how the result is formatted. It also omits any mention of the temporal/hard_stop behaviors that are present in the schema but not referenced in the description. An agent would need to inspect the schema fully and still might not know when to prefer this over other evidence-related 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?

Schema description coverage is 75% (3 of 4 parameters have descriptions), so the schema handles most parameter explanation. The description adds minimal value: it only implies candidate_id is the identifier ('for one candidate id') and does not elaborate on format, temporal, or hard_stop. For the undocumented candidate_id, the description gives a hint but not full semantics. Given coverage is not high (>80%), the description should compensate more but does not.

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 clear verb+resource: 'Return the complete neutral evidence capsule for one candidate id.' It also differentiates from verdict-producing tools by explicitly noting 'no safe/unsafe verdict,' which helps distinguish it from siblings like guard_dominance. However, it does not name any sibling tool or explicitly contrast with other candidate-related 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?

There is no explicit guidance on when to use this tool versus alternatives. The only hint is the phrase 'no safe/unsafe verdict,' which implies it should be used when a verdict is not needed, but this is implicit and not actionable. No alternatives or exclusions are mentioned.

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

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

With no annotations provided, the description fully carries the burden of behavioral disclosure, and it does so thoroughly. It explains that leads are never suppressed due to constant size, nearby guards, or absent input flow; describes the paged result structure; notes serialization per session and the expensive first cold bind; and explains how temporal evaluation degrades on hard_stop expiry. This is a comprehensive behavioral disclosure.

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

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

The description is four sentences with no filler. The main purpose is front-loaded, followed by critical behavioral caveats and alternative tool routing. Each sentence earns its place and the structure flows logically from core function to edge behaviors.

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 10 parameters, no annotations, and no output schema, the description covers the most important behaviors and key parameters, but leaves several parameters (limit, offset, cursor, domain, constructor_id, language) without explanation. It also lacks a description of the exact lead structure beyond paging fields. While the core is well-covered, the incomplete parameter documentation prevents a higher score.

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 only 40%, so the description must compensate. It adds meaningful context for temporal and hard_stop (e.g., the temporal_evaluated flag), and explains the pagination fields (leads, total, next_offset). However, it does not describe limit, offset, cursor, domain, constructor_id, language, or format beyond what the schema already says, leaving these parameters without additional semantic guidance.

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 direct verbs ('Enumerate and rank') and a precise resource ('every observable obligation site as leads'), and immediately distinguishes itself from the sibling candidate_census by noting it provides a pointer rather than a full roster. This leaves no ambiguity about what the tool does and how it differs from similar 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 gives explicit guidance to call candidate_census for the full coverage roster, and instructs when to set temporal=false for the fast path ('use it when a large graph makes the full bind run long'). It also states this is 'not a safety check', implying it should not be used for safety verification. This is strong, though it doesn't enumerate all alternative siblings or exhaustively list when not to use 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?

With no annotations provided, the description carries the full behavioral burden and does so well. It states read-only access, the exact facts returned, the absence of generated interpretation, newest-first ordering, and paging via limit/offset. This gives the agent a strong mental model of the tool's behavior beyond any structured metadata.

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?

Three compact sentences front-load the most important fact ('Read-only'), then state purpose, constraints, use cases, and behavior with no filler. Every clause 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 four-parameter tool with no output schema and no annotations, the description is unusually complete: it covers safety, return contents, output style, ordering, paging, and intended use. An agent has enough context to select and invoke this 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 description coverage is 100%, so the baseline is 3; the schema already explains symbol, limit, offset, and format. The description adds 'newest first' ordering and confirms paging semantics, but it does not meaningfully expand parameter meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource ('Join a symbol to its Git history') and clearly states the output: exact commits, author, date, subject. It also differentiates itself from explanation-style siblings by explicitly saying it returns history facts only and no generated 'why' narrative.

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

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

Gives concrete use cases: 'date a change or find who last touched a function'. It also implicitly tells the agent when not to use it by stating 'no generated why narrative'. However, it never names an alternative tool for those narrative cases, so it stops short of fully explicit when-not guidance.

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

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

With no annotations provided, the description carries the full burden and does substantial work: it explains the algorithm (label propagation), the input domain (call graph), the independence from directory structure, the community attributes (label, size, cohesion, files, top members), modularity reporting, and connector hubs. It does not explicitly state read-only behavior or side-effect absence, but the behavior it discloses is rich and accurate for a graph-analysis tool.

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

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

The description is dense but well structured: it front-loads the core concept, then output details, then the report-level outputs, then the parameter condition, then the usage workflow. Every sentence adds distinct information, and the length is justified by the algorithmic 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?

The tool is complex and has no output schema, but the description compensates well by enumerating the community fields and the graph-level reports (modularity, connector hubs). The main gap is that four of five parameters are not semantically explained in the description or schema, so an agent cannot fully reason about how n, members, and min_size affect the returned communities. Overall this is close to complete for default-parameter usage.

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 only 20%, so the description must compensate for the four undocumented parameters. It only meaningfully explains include_dispatch ('set include_dispatch for C function-pointer trees'). The parameters n, members, and min_size remain ambiguous despite defaults; the description mentions 'size' and 'top members' but does not clearly tie them to members or specify what n controls.

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 what the tool does: it partitions the call graph into communities/clusters using label propagation, independent of directory layout. It names the output concept ('codebase's SUBSYSTEMS'), gives concrete output fields, and distinguishes itself from the sibling tool hubs by sequencing: 'Use AFTER hubs to go from what is central to what are the parts.'

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 says to use it after hubs, which gives a clear workflow context and differentiates it from that sibling. It also gives a specific condition for include_dispatch on C function-pointer trees. However, it does not mention when NOT to use it or name other alternatives beyond hubs, so it stops short of full guidance.

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

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

With no annotations provided, the description carries the full burden, and it does well: it declares 'Read-only', specifies both directions, lists the covered reference types, and names the output fields (confidence, file:line). It does not discuss pagination, limits, or potential performance cost, but the core safety and return behavior are clearly disclosed.

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

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

Three tight, purposeful sentences. The read-only safety signal is front-loaded, the primary capability and output are stated immediately, and the sibling alternative is given in one clause with 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?

For a tool with five parameters, no output schema, and no annotations, the description covers purpose, scope, directionality, output contents, component semantics, and the main alternative. It could go slightly deeper on how limit/offset interact or what 'both directions' means for the from/to parameters, but overall it is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds context by defining components as path prefixes and giving an example, but this largely reinforces the existing schema descriptions rather than providing significant new parameter-level meaning.

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

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

The description uses a specific verb ('Show') and names exactly what is returned: every call, callback, and type reference crossing between two path components, in both directions, with confidence and file:line. It clearly differentiates from the sibling cross_boundary_paths by noting that sibling adds rarity ranking.

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 use this tool to audit the contract between two modules/dirs, and identifies cross_boundary_paths as the alternative when rarity ranking is needed. This is strong, direct usage guidance that an agent can act on.

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 behavioral disclosure. It meaningfully discloses offline-only behavior and that no implicit downloads happen, plus the explicit installation step. That is valuable non-obvious context beyond the bare fact that this is a search tool.

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

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

Two sentences, front-loaded with the core purpose, and no wasted words. The critical distinction (behavior vs spelling) is stated first, and setup details follow economically.

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 six parameters, no output schema, and no annotations, so the description should fill more gaps. It covers offline behavior and setup, but does not explain what results look like, how scoring works, how pagination behaves, or what the model parameter means. This is enough to orient an agent, but not enough to invoke it correctly with confidence.

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 only 17%, so the description must compensate for parameter meaning. It explains the semantics of semantic search generally and refers to the embedding model, but it does not explain query, limit, offset, min_score, model, or format beyond what defaults suggest. This leaves the agent without meaningful guidance for most 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?

The description uses a specific verb and resource: 'Search code by behavior rather than spelling.' This clearly distinguishes concept_search from sibling tools like search by identifying it as semantic/behavior-based rather than lexical. The name and title are not just restated; the description earns its 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 conveys when to consider this tool: when you want behavior-based search rather than spelling/lexical search, and it provides important setup context. However, it never explicitly names alternatives or says when not to use this tool, leaving part of the routing decision to the agent rather than stating it.

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

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

With no annotations, the description carries the full behavioral burden, and it does so reasonably well: it reveals that the result is intentionally 'minimal', which categories are included, that unknowns are made explicit, and that the relevance method is identifier/graph-based until concept_search is ready. This gives an agent a genuine sense of what behavior to expect, even if side effects and pagination details are not covered.

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 two sentences, front-loaded with the tool's core purpose, and every word earns its place. The second sentence adds the key caveat about the relevance engine without unnecessary elaboration.

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

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

For a 10-parameter tool with no annotations and no output schema, the description is adequate for basic usage: an agent can reasonably call it with just a question and consume the returned factual set. It clearly lists gaps around offsets and result-shape structure and does not mention decision criteria against sibling tools, so it falls short of being 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 description coverage is only 10%, so the description must compensate for the many undocumented parameters. The category list (symbols, relationships, conditions, tests, specs, unknowns) maps directly to the six offset parameters, adding real meaning. However, it still leaves the semantics of max_symbols, max_neighbors, and the question parameter implicit, and does not explain pagination/offset usage.

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 action and deliverable: 'Return a minimal coherent factual set for a code question' and the full list of content types (symbols, call relationships, conditions, tests, specs, and unknowns). It also distinguishes itself from concept_search by explaining that it uses identifier/graph relevance until embeddings are configured.

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

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

The description clearly implies this is for open-ended code questions and for services far as a fallback to concept_search. It does not explicitly identify when to prefer it over search, callers, tests, or other siblings, nor does it name any alternatives besides concept_search. So usage guidance is present but not 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 behavioral burden. It clearly discloses that the search is bounded and truncated, and that this makes a negative result non-conclusive. This is a significant and honest behavioral caution. It does not spell out output format or what happens on no result, but the core semantics are disclosed.

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

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

Two sentences with no filler. The first sentence defines what the tool does with the concrete resource and constraints, and the second is a valuable caveat that clarifies the meaning path absence. 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 six parameters, no annotations, no output schema, and low parameter documentation, the description is a bit thin. It covers the core operation and the truncation caveat, but does not describe the return value shape, the exact roles of `depth`/`limit`, or error behavior. However, the default values and schema names provide enough baseline to call the tool if the agent makes reasonable assumptions.

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 only 17%, so the description must compensate. It clarifies src, sink, and validator as source, destination, and the guard being avoided. Depth and limit are only indirectly covered by the words "bounded" and "truncated," and their specific semantics are left to the schema defaults.

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 operation: find a bounded call path from src to sink that avoids a named validator/guard. It also positions this as "the inverse reachability move," which distinguishes it from reachability-oriented sibling tools and signals that it creates counterexample paths rather than ordinary reachability results.

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 this tool through "inverse reachability move," but it does not explicitly name alternatives or state what should be used instead in other scenarios. The caution that absence of a path is not proof when the search is truncated is helpful, but the when-to-use guidance is mostly implicit.

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 disclosure burden. It openly states 'Read-only', clarifies the tool is deterministic, and defines its scope ('measures what the graph contains'). It lacks details on response formatting or error behavior, but for a reporting tool the key behavioral traits are covered.

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?

Three sentences with no filler. The read-only flag is front-loaded, the purpose is stated immediately, and the use-case guidance earns its place. Nothing is redundant.

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 purpose, read-only behavior, scope boundaries, a decision-oriented use case, and parameter optionality. With no output schema, it does not need to detail return values; the format parameter already hints at text vs json output. Missing an explicit note on pagination is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents limit, format, offset, and component_depth. The description adds only 'All params optional' and contextual meaning ('by component'), which is useful but not enough to push above the baseline.

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

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

The description states a specific verb-resource pair ('Report deterministic graph coverage by component') and enumerates concrete outputs (files, callable bodies, diagnostics, unmodeled frontiers). It also distinguishes itself from per-client session activity, so an agent can tell it apart from activity-tracking siblings.

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

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

It gives a clear when-to-use trigger: 'use it to decide whether an empty result means clean or not analyzed'. It also states a what-not-for condition ('not per-client session activity'). However, it does not name any sibling tool as an alternative, so the guidance is good but not fully 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?

No annotations are provided, so the description carries the full burden. It does convey that this is a list-like, read-oriented operation and adds behavioral detail around boundary tags, rarity ranking, direction, and confidence preservation. However, it does not describe edge cases, ordering semantics, occurrence of no crossings, or interaction with pagination.

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 one concise, front-loaded sentence with minimal wasted words. It states the primary action, the scope, and the distinguishing result qualities without restating schema details.

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

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

Given no output schema and no annotations, the description still lacks enough context about result structure, pagination behavior, and the meaning of 'boundary' and 'rarity.' An agent may be able to invoke the tool based on the clear from/to naming, but the broader execution context is not fully specified.

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 only 20%, so the description needs to compensate by explaining parameters. It implicitly covers direction and from/to component, but it gives no specific meaning for limit, offset, or format. The description adds less value than the parameter names and the one enum description already provide.

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 concrete verb and resource: 'List crossings between two components.' It further defines what kind of result is returned: boundary tags, rarity ranking, direction, and confidence. This makes the tool's purpose reasonably distinct from a bare 'crossings' name, though it does not explicitly contrast it with sibling tools.

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

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

'Between two components' gives clear usage context and maps naturally to the required from_component and to_component parameters. The description does not mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description must carry the full burden. It does disclose idempotency, persistence, and the handling of unevaluated temporal families. However, it incorrectly claims 'No arguments' while the schema defines a 'format' parameter, which is a serious misstatement that misleads about invocation. This is a transparency failure beyond any good elements.

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 packed with useful information (benefit, persistence, idempotency) and is reasonably structured. It is long but each sentence carries meaning. The false 'No arguments' is a glaring error, but otherwise the text is concise and front-loaded with the main 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?

Given the tool's complexity (no output schema, no annotations), the description explains the effect, side effects, and idempotent behavior well. It misses nothing major except that it fails to mention the 'format' parameter (due to the false claim) and does not describe the output format, though the schema already covers that. Overall quite complete, but the parameter misinformation detracts.

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 parameters (format), so baseline is 3, but the description directly contradicts the schema by stating 'No arguments.' This actively misleads the agent into believing there are no parameters, undermining the schema's documentation. The description adds negative value by being factually wrong about the parameter count.

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: warming sidecars to speed up subsequent flow_pass/leads/candidates/explain calls. It specifies the resource ('this graph's sidecars', dataflow tier, catalog) and the action (folds, binds, persists), and even distinguishes itself by naming the sibling tools it benefits. It is specific and not a tautology.

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: before flow_pass/leads/candidates/explain to avoid cold costs. It also indicates idempotency, so calling it repeatedly is safe and a no-op if already done. However, it does not explicitly state when NOT to use it or mention any alternative tools for the same task, leaving some inference required.

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 safety/behavior burden. It explicitly states 'Read-only' and discloses the tool's limitation (transfer summaries remain separate). It does not describe the exact return shape or any potential error behavior, but the core behavioral profile is 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?

Three sentences, with the main purpose front-loaded and no redundant filler. The phrase 'honest frontier' is slightly vague, and the lifecycle-graph sentence is dense, but overall every sentence contributes to purpose, usage, or limitation.

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 reporting tool with only one required parameter, the description covers what it does, when to use it, and what it does not do. It lacks an explicit description of the response shape, but the absence of an output schema makes that a modest gap rather than a fatal one.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents function, limit, and format. The description adds no parameter-specific detail beyond that, which is acceptable given the 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 opens with a clear verb and resource: 'for one function, report its exit paths (returns / error branches) and the resource-handling evidence on them.' It separates itself from flow_pass by noting that complete transfer summaries are a separate frontier and by positioning itself as companion to guards/flow_pass.

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 says exactly when to use the tool: 'Use it to see how a function leaves on its error paths.' It also gives alternatives/complements by instructing the agent to 'pair with guards and flow_pass for the interprocedural picture,' and warns that complete transfer summaries are out of scope.

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 takes on the full disclosure burden and opens with 'Read-only,' clearly establishing the safety profile. It also reveals that the trace is bounded, follows resolved indirect dispatch, and returns an ordered structure rather than prose. It does not detail result format or error behavior, but the critical behavioral traits are spelled out.

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 three dense sentences with no filler, front-loading the most important facts: read-only, bounded, entry-point trace, and non-narrative output. Every clause contributes to selection or invocation decisions.

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 8 parameters, no output schema, and no annotations, the description covers what the tool does, when to use it, how to bound it, and how to page results. It leaves the exact returned structure to the `format` parameter, but the mental model of an 'ordered structure of what runs' is sufficient for safe initial invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds a helpful conceptual grouping—max_depth/max_steps as cost bounds and branch/frontier offsets as paging controls—but does not introduce new parameter-level meaning or syntax beyond what the schema provides.

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

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

The description states a specific operation—a bounded forward call-and-branch trace from an entry point—and makes the output type explicit by distinguishing it from generated narrative prose. It also names a sibling (`hubs`) that it is not, which strongly aids tool 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?

It gives explicit when-to-use guidance: 'Use it to see the control skeleton reachable from an entry.' It also provides a when-not-to-use alternative: 'For pure centrality use `hubs` instead,' plus practical instruction on bounding cost via max_depth/max_steps and paging branches/frontier.

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 full disclosure. It explicitly warns that 'provenance and guard are evidence, not verdicts' and that an empty cone means 'nothing observed under this tier,' not 'unreachable.' It also details the temporal fast path and hard_stop degradation behavior, including the result's 'temporal_evaluated' flag. This is substantial and non-obvious 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 a single dense paragraph with long, compound sentences full of technical jargon (e.g., 'bounded reverse value-flow cone,' 'census->candidates->detail->sources_of->read_body chain'). While every sentence adds information, the sheer length and convoluted phrasing reduce usability. It could be split into bullet points or shorter sentences without losing content.

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

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

Given the tool's complexity (8 params, no output schema), the description covers the essential behaviors: what result is produced (obligation, guard, cone, source), interpretation of results (evidence vs verdicts), fast-path and timeout behavior, and invocation patterns. It mentions result flags (temporal_evaluated) which is helpful. No critical gaps apparent for an expert user, though it assumes domain familiarity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying the mutual exclusivity of candidate_id vs file+line, and by explaining the temporal parameter's effect on evaluation completeness. However, it doesn't add details beyond what the schema already provides for parameters like format, max_source_chars, or provenance_limit. It's adequate but not enriching.

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 what the tool does: it produces a composite 'judgeable picture' from a candidate or sink location, bundling obligation, guard, reverse flow cone, and source code. It distinguishes itself implicitly by describing a chained pipeline (census->candidates->detail->sources_of->read_body) that no sibling explicitly offers, though it doesn't name a specific alternative. The verb 'explain' is vague, but the resource and outcome are 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?

The description instructs to 'Pass candidate_id, or file and line,' giving the primary invocation choices. It also mentions the temporal parameter for a fast path but doesn't explicitly say when to choose this tool over other siblings like candidate_detail or sources_of, nor does it state exclusions or prerequisites. Some context is given (e.g., use temporal=false for large graphs), but no comparative guidance.

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

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

With no annotations, the description carries the full transparency burden. It conveys a read/list posture and adds meaningful context: results are graph-evidenced, oriented to field/property lifecycle events, and include owning functions. It does not disclose pagination behavior, ambiguity handling, or whether these events are purely inferred from an existing graph.

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?

One dense, front-loaded sentence. It opens with the resource ('For a field/property') and packs the important event taxonomy into a compact list without repetition 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 5-parameter tool with no output schema, the description is only minimally complete. It specifies the result content (event types and owning functions), but leaves important context implicit: how the 'field' is represented, how owner_type disambiguates, and how limit/offset shape the returned page.

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 only 40% of parameters with descriptions. The tool description partially compensates by clarifying that the field parameter refers to a field/property and that owning functions are part of the output. It does not explain field-name syntax or the relationship between field and owner_type 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 clearly states a verb ('list') and a resource ('field/property') and enumerates specific event categories: initialization, modification, reads, checks, and value-flow events. It does not explicitly name sibling tools that overlap (e.g., flow, sources_of), so it stops 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 'For a field/property' gives a clear implied usage context, and listing event history is a reasonable trigger condition. However, it gives no explicit 'when not to use' guidance and does not compare against alternatives like flow or object_lifecycle.

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 delivers: declares read-only safety, discloses the return shape (labeled nodes/edges), and — most valuably — states the over-approximation caveat that a missing path is not proof of absence. Also reveals the algorithmic behavior of bridging aliases through the heap.

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?

Three sentences with zero waste: what+relations, when+alternatives, return+caveat each earn their sentence. The read-only flag and core action are front-loaded for immediate orientation.

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?

Strongly complete for a complex graph-analysis tool with no output schema: selection guidance, safety profile, return format, and the key soundness caveat are all present. Minor gap: the interaction between limit=200 truncation and the 'missing path is over-approximation-safe' claim is not addressed.

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 100% of parameters, so seed, limit, and format are already documented there. The description adds some semantic color (traversal over VALUE_FLOWS_TO + POINTS_TO, 'from a value/symbol'), but this mostly reinforces the schema's seed description rather than expanding on it. Baseline 3 is appropriate.

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

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

States a precise verb+resource pair ('Forward value-flow cone') and the exact graph relations involved (VALUE_FLOWS_TO + POINTS_TO), including alias-bridging through the heap. This sharply distinguishes it from the sibling set — sources_of (reverse direction) and reaches (yes/no witness) are explicitly named as different 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?

Gives an explicit selection rule — 'Use it to answer where does this value go?' — and names the two closest alternatives with their exact conditions: sources_of for the reverse (what feeds a sink) and reaches for a yes/no witness. An agent can route correctly with zero inference.

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

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

With no annotations provided, the description carries the full burden. It discloses that the call 'materializes and caches the pass' (a behavioral trait), always returns counts and a bounded lead page rather than the whole graph, and details the summary structure. It does not mention read-only status or performance, but these are secondary. It adds meaningful behavioral context beyond a trivial 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 several sentences but every one adds value: it defines the action, enumerates the output contents, explains the caching/materialization, and gives usage hints. It is efficient and well-structured, with key details 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 no output schema, the description does a strong job of describing what will be returned (counts, lead page, specific signature types) and how to scope/paginate. It also notes constraints (never whole graph). It could be more complete by mentioning when this pass is appropriate relative to alternatives, but given the complexity, it's sufficiently complete for an agent to decide to call it and understand results.

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

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

Schema coverage is 50% — only function and format are described. The description compensates by explicitly linking offset and limit to pagination ('paginate with offset/limit') and clarifies function's role ('scope to one function'). This adds meaning that the schema alone does not fully convey, especially for the two undocumented 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?

The description states a very specific action: run the interprocedural flow pass and return a per-function summary census. It enumerates exactly what the census contains (taxonomy, taint source, sink-flow signatures, pointer lifetime signatures) and distinguishes it as 'the layer beneath the skeletons' and the composed summary for the shape matcher. This clearly separates it from sibling tools like flow, flow_skeleton, or taint.

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

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

The description gives explicit usage instructions: 'Use function to scope to one function; paginate with offset/limit.' It also sets expectations that the response is a bounded lead page, which guides caller behavior. However, it does not explicitly state when not to use this tool versus the siblings (e.g., when to use skeleton vs flow_pass), nor name alternatives. So it provides context but lacks explicit exclusions.

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 zero annotations, the description carries the full behavioral burden and largely delivers: it discloses the return semantics (LEADS, not verdicts, to be adjudicated elsewhere), the bounded paginated response ('reports graph counts, never the whole graph'), and the default ordering ('source-rooted first'). This is meaningful behavioral disclosure beyond a bare mutation/read hint.

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?

Dense and front-loaded with the core purpose; every sentence earns its place, including the return-type caveat and pagination bound. It is a long, jargon-heavy wall of text ('nesting-aware {control|sink|lifecycle} streams STITCHED across call seams'), but the complexity of the tool justifies the length and no sentence is filler.

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

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

With no output schema, the description correctly compensates by explaining return values (leads, graph counts, never the whole graph), default scoping, and parameter-driven narrowing. It covers everything needed to invoke correctly, though it leaves the relationship to the broader flow family (flow, flow_pass, leads, taint) unclarified — a minor gap against the sibling set.

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 60% (kind, format, function are described; limit/offset only have defaults). The description adds real semantics beyond the schema: `function` scopes to one entry and renders skeletons, `kind` filters reach|typestate, and the no-arg case yields every lead, source-rooted. Limit/offset are self-evident pagination with schema defaults, so the modest gap is acceptable.

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-resource pair ('compose per-function summaries into linear, nesting-aware streams STITCHED across call seams') and explicitly names what it is NOT: the single-function `skeleton`. The two skeleton kinds (REACH, TYPESTATE) are each given a concrete definition with the bug classes they feed (double-free/use-after-free/leak). An agent can distinguish it from its closest sibling `skeleton` on purpose alone.

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

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

Gives clear routing context: it explicitly contrasts with the single-function `skeleton`, and tells the agent the output is LEADS to be adjudicated with sources_of/reaches, plus the no-arg default behavior. It does not, however, spell out when to pick this over the many other flow siblings (flow, flow_pass, leads, taint) beyond the single-function contrast, so exclusions are implied rather than enumerated.

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 behavioral transparency burden and does meaningful work: it states that the tool returns proven, skippable, or undecided evidence and explicitly declares that it never emits a safety verdict. This is important non-obvious behavioral information, absent even though the tool is inference-oriented.

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

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

Two tight sentences with no filler. The action is front-loaded, the result vocabulary is compact, and the 'never emits a safety verdict' clarification earns its place because it prevents the agent from misusing the result.

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 moderately simple graph-analysis tool, the description covers the main query, the input relationship, and the result classes. There is no output schema, so the description is the only place where the return concept is defined; it does define it. It would be stronger if it also explained what happens for unrecognized guards or unsatisfied preconditions, but the definition is still usable.

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 phrase 'entry-to-effect call path' adds meaning to the two required string parameters, entry and effect. However, with schema description coverage of only 25%, the description still leaves depth undefined and does not clarify how the optional parameters interact with the dominance analysis. It partially helps but does not fully compensate for the sparse 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 uses specific language: it checks whether recognized guards dominate an effect, and explicitly states the result is evidence rather than a safety verdict. This cleanly separates it from a safety-assessing tool. It doesn't name a particular sibling to differentiate from, but the main operation is clear.

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 the tool is useful: when you need guard-dominance evidence on an entry-to-effect call path. It also implies when not to use it: when what you actually need is a safety verdict. But it provides no explicit when/when-not guidance and names no 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?

No annotations are provided, so the description carries the full burden. It clearly discloses the UNION graph scope, the ranking rule, row contents (node_id, handle, fan_in/out, degree), and important entry-point flags (exported | dispatch_target | callback), and that it is read-only for cold resolution. It does not explicitly state whether it requires a pre-loaded graph or triggers a rebuild — a small but meaningful gap — but the idea of full behavior is well conveyed.

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?

Three sentences, which is compact. The ordering is sensible: it declares the core semantics and scope, then the output fields, then the usage workflow. The sentence structure is somewhat dense (row field list is long), but nothing is wasted and the agent gets the necessary qualifiers — it touches a good balance.

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 carries the load for a tool with no annotations and no output schema: it describes the computation scope and the exact output fields. It misses clear pagination/limit behavior and the relationship to load_graph/build_graph (whether the underlying graph state matters). Overall it's a solid, self-contained, minimal-missing-context definition relative to 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 schema explains 25% of the parameters (only 'format' is described); the description names the format but mostly does so implicitly. It does map 'n' to the 'HIGH n highest-degree nodes' phrase, and the output row structure clarifies some of the output semantics. However, the distinction between 'n' and 'limit' and the pagination meaning of 'offset' are not explained and the schema description adds nothing.

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?

Identifies a very specific operation: the highest-degree ranked functions over the union of direct and indirect call graph edges, with fan_in + fan_out as the ranking key. It clearly differentiates from traversal tools (callers/callees/read_body) by calling itself the 'spine' and the fallback first step.

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

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

Provides an explicit usage directive: 'start here to find what a subsystem is built around, THEN callers/callees/read_body to navigate.' The phrase 'no name knowledge needed' also helps distinguish it from name-requiring alternatives like search. Lacks an explicit 'when NOT to use' statement, but the general-methodology is clear.

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?

There are no annotations, so the description carries the burden. It does disclose useful behavioral traits beyond the operation itself: unresolved sites are kept visible and confidence is reported. It does not state whether the operation is strictly read-only or describe how confidence is represented.

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?

One tight, front-loaded sentence that names the operation, the target kinds, the scope, and the most important output behavior. There is no filler or repetition.

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

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

The tool has five parameters, no output schema, and no annotations, yet the description does not explain output shape, pagination, confidence semantics, or target_offset. This is not enough for an agent to call it correctly without additional investigation.

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 only 20%, and the description adds little parameter-level meaning. It obliquely maps 'function' to the scope, but it leaves target_offset, limit, offset, and function-reference format largely unexplained. For five parameters, more compensation is needed from the 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 states a specific verb ('Resolve'), a concrete resource ('function-pointer, callback, ops-table, and runtime dispatch sites'), and a clear scope ('inside a function'). This is specific enough to distinguish it from siblings such as callers, callees, or candidates without needing to open 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?

The description implies its use: when indirect dispatch targets inside a function need resolving. However, it does not explicitly say when to choose this tool over similar siblings like candidates, callers, or flow, nor does it give any when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden and discharges it well: it declares 'Read-only' up front, which is the key safety behavior. It also discloses the return shape (role-tagged nodes with file:line) and the bounded nature by `depth`. It does not discuss failure modes or performance, but for a read-only analysis tool the essential behaviors are covered.

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?

Three sentences, each earning its place: the first defines the operation, the second gives the use case and return format, the third draws the boundary against alternatives. The 'Read-only' safety cue is front-loaded, and there is zero fluff or repetition.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description provides enough to call it correctly: it explains the return structure, the local scope, and how to choose a different tool. The only minor gap is that `format`'s text vs json behavior is not explicitly referenced in the description, though the schema covers it.

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

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

Schema coverage is 100%, so the baseline applies. The description does add a small semantic link by saying results are 'bounded by `depth`', but this largely echoes the schema's own 'how many flow hops' wording. It adds no meaning for `value`, `limit`, or `format` beyond what the schema already states.

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

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

The description opens with the specific verb 'Trace' and clearly defines the resource: producers, mutators, checkers, and consumers of a value or field over a bounded local flow cone. It explicitly distinguishes itself from interprocedural siblings like `flow` and `sources_of` by stating 'Local, not interprocedural', leaving no ambiguity about its scope.

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 states when to use the tool ('Use it to reconstruct an invariant around one value') and explicitly routes the agent to alternatives when the task crosses call seams ('use `flow` / `sources_of` to cross call seams'). This is direct, actionable guidance that prevents mis-selection among the many 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 fully discloses core behaviors: cached vs fresh, honesty fields, partial-run caveat, serialization, bounded/paged results, and file resolution semantics. This is exemplar.

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?

Though lengthy, it packs crucial context (caching, honesty fields, source position resolution, adjudication routing, serialization/paging) with no redundancy. The core purpose is front-loaded, and each clause 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?

Covers purpose, usage routing, behavior, parameter semantics, and caveats. Lacks a detailed return shape for text/json, but gives a high-level summary and mentions pagination. Given no output schema, the description provides sufficient guidance for invocation, though exact lead fields (beyond function+line) are not enumerated.

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 description enriches parameter semantics beyond the schema: it explains the `at` format and file resolution process, clarifies that `pattern` and `function` filter the cached result, and describes the no-arg summary behavior. Even though schema covers most parameter names, the description adds usage context that improves correct invocation.

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 (query), resource (flow pass's LEADS in memory), and explains it's not a fresh cold run but a filtered view of a cached result. Also names siblings (flow_pass, sources_of/reaches) for 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?

Explicitly states the tool is a warm counterpart to a cold run, references flow_pass for materialization, and directs to sources_of/reaches for adjudication, effectively routing usage. Also mentions session serialization and paging constraints.

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 behavioral burden. It explains that the graph is loaded once and subsequent tools all operate on the in-memory copy, which is important state-changing behavior. It stops short of describing side effects like whether the old graph is discarded or if this can affect producers, but the core behavior is disclosed.

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

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

The description is two dense sentences with no redundancy. The primary function is stated first, followed by the input shape and global side effect, which makes it easy to scan and reason about.

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

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

Given that there is no output schema, this description covers the essential context: what the tool does, the provided inputs, and the side effect. It is somewhat sparse on error conditions or preconditions, but it is complete enough for selecting the tool in a normal workflow.

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 offers no description of the parameters, so the description must compensate. The description adds useful meaning: the path is a canonical graph JSON path, and overlay + profile are optional. Still, overlay and profile semantics are not fully explained, so an agent has to guess their purpose or consult external knowledge.

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

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

The description names a specific verb and resource relation: switch/attach the active graph the server reasons over, with an example of retargeting to a different graph. It clearly differentiates itself from loading/creating a new graph because it describes a session-wide swap of the in-memory active graph, which also distances it from the build_graph sibling.

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

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

It gives concrete operational context: use this to change the active graph mid-session without restarting, e.g. from bnxt to igb. It does not explicitly say when not to use it or name alternative tools, but the scenario is clear enough for an agent to decide it is the tool for switch/attach operations.

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 delivers: it declares 'Read-only' up front, clarifies the tool reports existing graph evidence rather than computing new analysis, discloses the no-arguments capability report behavior, and lists the output categories. It does not address edge cases like conflicting value+function scoping or missing nodes, but for a read-only reporting tool the disclosure is strong.

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?

Three sentences with zero filler. The 'Read-only' safety signal is front-loaded, the core function and its output contents are in sentence one, scoping instructions in sentence two, and routing to alternatives in sentence three. Every clause 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 tool with no required parameters and no output schema, the description covers the essentials: what the report contains, how to scope by value or function, the no-arg capability report, and the format default. Minor gaps remain — the contents of the capability report, behavior when both value and function are supplied, and failure behavior for unknown nodes — but nothing that would block correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all three parameters. The description adds value beyond the schema by explaining the interaction semantics: value and function are alternative scoping modes, omitting both yields the capability report, and format's default is text. This relationship information is not present 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 states a specific verb ('Report'), a specific resource ('lifecycle evidence the graph holds'), and a concrete scope (value or function). It enumerates exactly what the report contains — Pass 3 alloc/release/deref/alias/generation events, source-rooted coverage, and matcher leads — and explicitly names sibling tools (field_history, flow_pass) as the alternatives, making its niche unmistakable among 44 siblings.

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

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

Gives explicit selection guidance: 'Give `value` or `function` to scope it; omit both for the capability report' states the argument modes, and 'Prefer `field_history` for one field's events and `flow_pass` for the composed interprocedural summary' names the alternatives and the conditions that select them. No inference is required from the 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 present, so the description carries the full burden. 'Returns' signals a read-style operation and the output shape is disclosed. However, important behaviors such as missing-file handling, whether a graph is always immediately available, or any cost/indexing assumptions are not mentioned.

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 two short sentences with no filler. It front-loads the purpose and contents, then closes with the return shape, making it easy to scan and parse for an 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 tool with one required parameter, one optional format parameter, and no output schema, the description gives enough to make a valid call. The main gaps are the unexplained 'L1' concept and the fact that 'manifest' is mentioned but not defined, which could confuse an agent expecting richer 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 schema lacks documentation for the `file` field, and the description wisely adds semantic detail by specifying 'repo-relative path'. The `format` parameter is already fully documented in the schema with a description and enum, so no further parameter explanation is required.

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 concrete behavior: return an L1 file graph for a file, and lists the graph contents (imports, declarations, intra-file calls, cross-file jump-stubs). It also gives the output shape, so the purpose is specific and not just a restatement of the name. It stops short of a 5 because 'L1' is not defined, and no sibling tool is clearly contrasted.

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?

'For one file (repo-relative path)' is a clear usage condition and should guide an agent toward this when a per-file graph is needed. It does not explicitly say when to avoid it or name a better sibling tool, so it is one level below full guidance.

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

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

With no annotations provided, the description carries the full burden: it opens with 'Read-only', which clearly signals a non-mutating safe operation, and it discloses the return shape as a {nodes, edges, manifest} graph. It also explains that the result is a coarse L0 view, which is important behavioral context for how the tool should be used.

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 two focused sentences. It front-loads the most important safety and semantic information ('Read-only', 'L0 folder graph'), then gives usage context and return shape with no filler.

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

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

Given there is no output schema, the description usefully names the return graph shape ({nodes, edges, manifest}). It also explains the folder->file->declarations hierarchy and how this tool fits the navigation workflow. It could go slightly deeper on what 'manifest' contains, but for an orientation tool, the coverage is strong.

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

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

Schema description coverage is 100%, so the baseline applies. The description reinforces that 'root' is a path prefix and ties it to the graph orientation, but it does not add meaningful detail about the 'format' parameter 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 names a specific operation (open a folder graph) with a clear resource and scope: an L0 folder graph rooted at a path prefix, with the structure folder -> file -> declarations. It also distinguishes itself from the sibling tools open_file and read_body, making its role 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 says this is the coarsest orientation move and should be used to see what lives under a directory before drilling in with open_file or read_body. This gives clear when-to-use guidance and names concrete alternatives, so an agent knows how to route among related 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?

No annotations are provided, so the description carries the full burden. It opens by stating 'Read-only', discloses result characteristics ('pointed-to objects with path evidence plus explicit unknowns'), and provides an important interpretative caveat: 'a missing edge is over-approximation-safe, not proof the pointer is null.' This goes well beyond the minimal safety statement and gives the agent meaningful 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?

Three sentences, each earning its place: the first states the operation and result, the second gives usage direction and exclusions, the third explains output nuance and a safety caveat. The most critical information (read-only, 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?

For a tool with 2 parameters, no output schema, and no annotations, this description covers everything needed for correct invocation: what it does, when to use it, what it returns, and how to interpret edge cases. The parameter schema handles the remaining structured details, so 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of 'value' by framing it as 'a value may point to', but adds no concrete parameter-level details beyond what the schema already provides ('value name or graph node id'). The 'format' parameter is also already fully described 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 states a specific verb and resource: 'Return the heap objects a value may point to through POINTS_TO edges — the alias set behind a pointer.' It clearly differentiates from sibling tools by explicitly saying 'not for callers (`callers`) or value-flow (`flow`/`reaches`)', so an agent can tell it apart without opening sibling schemas.

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

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

The description gives explicit when-to-use guidance: 'Use it for pointer/alias follow-up', and explicitly names the alternatives to avoid: 'not for callers (`callers`) or value-flow (`flow`/`reaches`)'. This leaves no ambiguity about when this tool is the right choice.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It starts with 'Read-only', states that real value-range analysis is unavailable until the numeric model ships, and notes that the response honestly reports that frontier. It could add return-shape or error details, but the core behavior is 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 two sentences with all critical information front-loaded: read-only, core purpose, limitation, and parameter guidance. Every clause adds value, and it remains compact despite conveying several nuances.

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 partially explains the return shape as a lightweight numeric evidence graph and a capability report. It does not detail pagination or response layout, but the schema covers limit and format, and the tool is simple enough that no major missing context blocks correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining parameter combinations: value and/or function, and what happens if both are omitted (capability report). This clarifies behavior 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 states a specific verb and resource: 'Return the lightweight numeric evidence graph guards expose for a value'. It also clearly distinguishes the tool from a full interval solver, which separates it from related analysis tools. The capability-report fallback is also explicitly 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?

The tool gives concrete scoping instructions: 'Scope with value and/or function; omit both for the capability report.' It also clarifies what the tool is not ('not a full interval solve'), but it does not name an alternative sibling tool, so the when-not guidance is implicit 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 and does so excellently. It discloses the operation is read-only, describes the output (labeled witness path or honest negative), explains the truncation caveat, and clarifies the exact edge semantics. This goes well beyond a typical tool description.

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

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

The description is compact and front-loaded: it opens with 'Read-only' and the core question, then adds essential caveats and usage guidance. Every sentence earns its place, and there is no redundant or filler content.

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

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

Despite having no output schema or annotations, the description gives an agent enough to use the tool correctly: purpose, output nature, edge-set semantics, truncation limitation, and sibling alternatives. It anticipates the most likely confusions, making it complete for this analysis-oriented tool.

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

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

Schema description coverage is 100%, so the baseline holds; the schema already documents `src`, `sink`, and `format`. The description adds contextual meaning by framing the parameters as a specific source->sink pair, but it does not add significant semantic detail beyond what the schema provides.

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

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

The description clearly states the tool's function: it checks whether a source reaches a sink through value flow and returns a labeled witness path or a negative. It also distinguishes itself from siblings by naming the specific edge set and contrasting with `flow`/`sources_of` and `taint`.

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

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

It explicitly says when to use this tool ('confirm one specific source->sink pair') and when not to ('use `flow`/`sources_of` to explore a whole cone'). It also warns that `reaches` follows VALUE_FLOWS_TO/POINTS_TO rather than the taint edge set, preventing misuse.

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 full burden. It discloses output fields, the max_chars cap with truncated flag, and the best-effort fallback behavior when file/offsets are unavailable. It does not state explicit error behavior or read-only non-mutation guarantees, but 'read' plus the detail given is strong.

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

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

The description is compact and front-loaded. The first sentence establishes the move, the second specifies input and output shape, and the third covers fallback behavior. No sentence is wasted.

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

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

The description gives enough to call the tool successfully: accepted identifiers, return content, truncation behavior, and fallback. It doesn't describe invalid-input behavior or what happens if neither name nor node_id is provided, but that is a minor gap given the rest of the detail.

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

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

Schema description coverage is only 25%, so the description compensates: it explains that name or node_id identify the function, and that max_chars caps output with a truncated flag. Format is still left to the schema enum, but the description covers the otherwise underspecified key 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?

States a clear action ('Read') and resource: 'a function/method's real source (L3)'. It is specific enough to distinguish from generic file-reader siblings and explicitly contrasts itself with cat.

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 establishes this tool as the default 'open this and read it' move for function/method source, saying the agent should not fall back to cat. It provides clear context for when to use it, though it doesn't explicitly list when not to use sibling tools like open_file.

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 behavioral burden and does so explicitly: 'Read-only' signals safety, and 'Returns the differences as facts only, inferring no semantic verdict' discloses both the output style and the tool's interpretive restraint.

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

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

Two dense sentences front-load the most important trait ('Read-only') and then state scope, output behavior, and the sibling routing. 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?

For a two-required-string tool with a simple format enum, the description covers purpose, scope, output nature, and alternative tool. There is no output schema, but the description's 'differences as facts only' plus the format parameter sufficiently sets expectations.

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

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

Schema coverage is 100%, so the schema already describes left, right, and format adequately. The description adds no parameter-level detail, which matches the baseline of 3 for 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?

Description states a specific verb ('Compare') and resource ('two functions/paths side by side'), and enumerates the comparison dimensions (graph-visible calls, control structure, conversions, side-effect differences). It also differentiates from sibling_compare by specifying this is a deliberate two-sided pairing rather than auto-discovered peers.

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 names the alternative tool and the condition selecting it: 'Use sibling_compare for auto-discovered structural peers, this for a deliberate two-sided pairing.' The encode/decode and serialize/parse examples further clarify when the tool applies.

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 covers key behaviors: return type (leads, not verdicts), output constraints (bounded, paged), response contents (coverage and temporal work completion), concurrency semantics (serialized per session), and runtime selection (native selected internally). This is comprehensive and leaves little ambiguity about side effects or state.

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 succinct and front-loaded with the core purpose, then transitions to lens options and finally operational details. It avoids redundancy and stays within a few sentences. The structure is logical, though the multiple clauses about behavior could be slightly more organized with bullets, but overall it is well-compact.

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 8 parameters, no output schema, and no annotations, the description covers the essential context: what it returns (questions), how results are bounded/paged, that response includes coverage and temporal status, and that calls are serialized. It does not describe the exact output format (e.g., JSON structure) or elaborate on all param semantics, but given the complexity, it leaves only minor gaps that the schema partially covers.

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 63%, so the schema already documents several parameters (lens, format, offset, hard_stop, entrypoints). The description adds semantic meaning for 'lens' (all vs. guard-diff vs. flow) but does not elaborate on the meanings or interactions of the undocumented parameters (limit, min_rank, include_suppressions). Given the moderate coverage, the description only partially compensates, so a 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-resource pair: 'Return ranked leads' from the whole taxonomy. It further clarifies the output nature ('questions to investigate, never verdicts') and provides lens-specific variants. It clearly differentiates itself from the sibling tools that focus on specific analysis (e.g., flow, guard_dominance) by mentioning distinct lens modes. This is unambiguous and minimally overlapping with sibling 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?

Explicitly instructs when to use alternative lens views: 'Use lens=guard-diff for the entrypoint-to-effect guard view or lens=flow for native object-lifetime leads.' It also sets expectations about results being bounded and paged, and mentions the serialized nature of calls. This gives the agent clear decision criteria without needing to infer.

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 behavioral disclosure burden. It reveals fuzzy matching, de-prioritization of test/spec symbols, paging behavior with limit/offset, real match totals, and the cold-graph ranking limitation. It does not explicitly state read-only semantics or the exact result envelope, but it covers the key behaviors well.

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 conveys a lot in two sentences without being bloated. Slight duplication exists between 'function/method/type/file name' and 'symbol', but each clause adds useful context.

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

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

For a tool with four parameters, no output schema, and no annotations, the description provides enough for an agent to know what to expect: canonical IDs, file:line positions, paging, de-prioritization, and cold-graph behavior. It stops short of specifying the exact return structure or error/empty-match behavior, but those absences are not severe.

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 only 25%, and the description compensates by clarifying name as a fuzzy symbol search and by explaining how limit/offset function, including de-prioritized results and real match totals. The only other parameter, format, is already documented by the schema enum and 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 action: resolve a function/method/type/file name to canonical node id(s) with file:line. It also differentiates itself from blind-name search and concept-oriented sibling tools by emphasizing symbol teleportation once the name is known.

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

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

The description gives explicit when-to-use guidance by noting that on a cold graph you should prefer guards_top first and only use this tool when you already know the name. This helps the agent avoid using the tool in a suboptimal 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?

No annotations are provided, so the description must carry the transparency burden. It does disclose an important behavioral boundary by stating that it returns 'differences as facts only' and 'does not rank anomalies or issue verdicts.' However, it does not clarify side effects, permissions, pagination behavior, or what the output actually looks like.

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 two clean sentences with no filler. It front-loads the core purpose and then adds a meaningful behavioral boundary without redundancy or ambiguity.

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, no annotations, five parameters, and an unexplained 'call_offset', the description is not sufficient for an agent to understand the full call contract. The description says what the tool does at a conceptual level but leaves important execution semantics unspecified.

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 the 'format' parameter has schema-level documentation, and the description adds no direct details for 'symbol', 'limit', 'offset', or 'call_offset'. The phrase 'Compare structurally similar callables' faintly implies that 'symbol' identifies a callable, but that is too indirect to compensate for the 20% 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 a concrete verb ('Compare'), a specific resource ('structurally similar callables'), and the comparison dimensions ('by callees and control structure'). The second sentence clarifies the output scope, which helps an agent distinguish it from other analysis 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 implies when this tool is useful: when you want factual differences between similar callables. However, it does not name alternative tools or provide explicit when-to-use versus when-not-to-use guidance beyond saying it does not rank or issue verdicts.

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 transparency burden. It discloses the elision of unrelated code, the ranking behavior, the annotation fields on each sink, and the drill-down relationship to `candidate_detail` or `sources_of`. It does not mention what happens with invalid inputs, no-argument calls, or very large functions, which prevents a 5.

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

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

The description is dense, front-loaded with the core operation, and built around a single coherent view: sink + guard + structure. Each sentence has a purpose, though the middle rationale sentence could be tightened without losing meaning.

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

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

Since there is no output schema, the description does the needed work of explaining what the returned view contains: sinks, annotations, and guard/branch structure. However, because the input schema has no required parameters, the behavior when neither `function` nor `candidate_id` is supplied is unclear, and priority for combined inputs is not stated. These are meaningful gaps 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?

The schema already covers all parameters at 100%, so the baseline is 3. The description mostly restates the schema semantics: `function` is a name or node id, and `candidate_id` focuses on an enclosing function. It adds no new parameter-level guidance beyond what the schema provides.

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

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

The description immediately names the operation and resource: 'Render a function's sink map as a pseudo-function.' It then lists exactly what is included: all sink families, size expression, destination-capacity status, guard dominance, and the controlling branch/loop structure. This is specific enough to distinguish the tool from siblings like `guard_dominance` or `sources_of`.

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

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

It gives clear invocation guidance: use `function` for the whole enclosing function or `candidate_id` to focus on its enclosing function. It also routes operand provenance to `candidate_detail` / `sources_of`, clarifying what `skeleton` is not for. It lacks explicit exclusions or any direct comparison against nearby siblings such as `guard_dominance`, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses read-only behavior, describes the return shape (labeled nodes and edges), mentions truncation/frontier metadata, and warns that a missing path is not proof of absence. This is substantial, beyond minimal behavioral disclosure.

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

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

Three sentences, each earning its place: purpose and trigger, return content, and a critical caveat. The key action is front-loaded 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?

For a simple read-only query with full schema coverage and no output schema, the description is largely complete: it covers purpose, output nature, and a non-obvious completeness caveat. It does not explain how limit/format shape the result or contrast with sibling flow tools, but those are minor given the schema and specificity.

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 sink, limit, and format. The description adds context for 'sink' by tying it to a selected candidate/sink, but it does not enrich parameter semantics beyond what the schema provides.

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

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

The description leads with a precise verb-resource pairing: a read-only reverse value-flow cone for a sink. It further specifies the operation's goal ('find values that may feed it') and distinguishes it from forward-flow tools by the word 'reverse' and 'cone' semantics.

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

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

It explicitly says when to use the tool: after a candidate or sink is selected. It does not name sibling alternatives or state when not to use it, but the trigger condition is clear enough for an agent to select it.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it declares 'Read-only', explains that results are paged via limit/offset, preserves standards URLs and file:line evidence, and clarifies the recorded-source behavior. This goes well beyond what the schema alone conveys.

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 three sentences with no filler, front-loaded with 'Read-only' and the primary action. Every sentence earns its place: purpose, paging behavior, and the recorded-source caveat.

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 and no annotations, the description is complete enough for an agent to invoke correctly: it states what the tool returns, how pagination works, what the input symbol means, and in which context it is useful. The parameter schema covers the remaining invocation details.

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 limit, offset, format, and symbol. The description reinforces that limit/offset control paging and that symbol can be a name or node id, but it does not add meaningful 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 states a specific verb and resource: 'Link a symbol to its documentation and source comments' and explains the concrete goal of recovering 'the spec/standard a function implements.' It distinguishes itself from graph-focused siblings like points_to and callers by emphasizing documentation/comment references and file:line evidence.

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

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

It gives clear context on when to use the tool: 'Use it to recover the spec/standard a function implements' and adds a useful condition — it reads recorded source so it works even when comments are outside the production graph. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and meets it thoroughly. It discloses the costly whole-graph value-flow build on first call, caching, the no-op condition, the distinction between catalog-driven and generic reaches, and the exact semantics of the witness `path` versus `reaches` edge sets.

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 every sentence earns its place: it front-loads the purpose, then gives cost, no-op behavior, output shape, and adjudication warnings. However, it is a single long unbroken paragraph with many nested caveats, which reduces readability for an AI agent scanning for key constraints.

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

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

For a complex tool with no output schema, the description covers a remarkable amount: witness shape, path semantics, CWE/model ids, caching cost, no-op condition, and the unwitnessed follow-up workflow. The main gap is that the `limit` parameter's truncation effect is never stated, so an agent might assume all reaches are returned.

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 67%: `format` and `atropos_only` are described in the schema, while `limit` is not. The description adds some semantic color around catalog-driven versus generic reaches, which helps interpret `atropos_only`, but it does not clarify `limit` behavior or the `text`/`json` format distinction beyond the schema. It also says 'returning each source->sink reach,' which could misleadingly imply no truncation despite the default limit.

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: 'Taint witnesses from the Atropos catalog,' immediately explaining the tool's core function. It clearly differentiates this tool from siblings by defining taint propagation through source->sink reaches with catalog model ids, CWEs, and file:line endpoints, and by explicitly warning not to use `reaches` for adjudication.

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

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

The description gives explicit when-to-use guidance and alternatives: it says to adjudicate from `path`, do NOT re-derive with `reaches`, and feed `unwitnessed` ids to `sources_of`/`flow`/`reaches`. It also states the tool is a no-op if the Atropos catalog is not checked out, which prevents wasted calls.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does so meaningfully: read-through the recorded source tree, uses exact rather than fuzzy matching, and returns complementary assertion evidence. It does not mention edge-case behavior such as missing symbols or pagination, but the core behavior is 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 two deliberate sentences with no filler. The main action is front-loaded, and the second sentence provides useful contextual behavior instead of restating the name or 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?

The description explains the tool's source ('recorded source tree'), scope ('test/spec files'), matching semantics ('exact references'), and output emphasis ('nearby assertion evidence'). Since there is no output schema, some output detail is not specified, but the essential invocation context is present enough for a tool of this simplicity.

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 low at 25%, and the description does not meaningfully compensate for the undocumented limit, offset, and format parameters beyond what their names and defaults already suggest. The description clarifies the symbol parameter through 'exact references to a symbol', but the other parameters remain semantically opaque.

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 action and scope: 'Find exact references to a symbol in test/spec files'. The contrast with the production graph in the second sentence helps distinguish it from graph-oriented siblings like callers, callees, or sources_of. It also signals that assertion evidence is included, which clarifies the tool's specific 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 phrase 'Reads the recorded source tree because tests are normally excluded from the production graph' gives clear context for when this tool is the right choice. It does not explicitly name the alternative tools to use for production-graph references, but the intent is still clear.

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 transparency burden. It leads with 'Read-only', explains that roles are graph-derived, and discloses pagination behavior for fields versus methods. It does not cover error behavior or missing-type handling, but the key safety and data-source traits are present.

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

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

Four short sentences, each carrying distinct value: safety, what is returned, when to use it, and how to paginate. There is no filler or redundant repetition of parameter names beyond what adds 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 query tool with fully documented parameters and no output schema, this description covers purpose, usage timing, read-only behavior, and pagination mechanics. It could be more explicit about return shape details, but the content list in the first sentence provides enough orientation.

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 real value by associating offset with field pagination and member_offset with method pagination, which the schema does not state. This clarifies how the two offset parameters differ.

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: 'Explain a type from graph facts' and enumerates the exact content: fields plus methods that construct, mutate, consume, or destroy it with graph-derived roles. This clearly distinguishes it from call-site-oriented siblings like callers/callees by focusing on the type's shape and handling.

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

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

Explicitly says to use it 'to learn a struct/class's shape and how it is handled before reading call sites', giving a clear contextual trigger. It does not name alternatives or state when not to use it, so it falls just short of full exclusion guidance.

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

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

With no annotations provided, the description carries the full burden and does meaningful work: it declares 'Read-only', explains a non-obvious behavioral guarantee ('separates proven-absent from couldn't-cross'), and warns against misreading missing facts as 'none'. It omits details like pagination behavior or result shape, but the core behavioral contract is disclosed.

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

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

Three sentences, each earning its place: the first defines the resource, the second captures a critical semantic distinction, and the third gives usage direction. The most important information is front-loaded, and there is no redundant 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 listing tool with four optional parameters and no output schema, the description covers purpose, behavioral nuance, and scoping. It lacks an explicit statement about default output format or when a scope is required, but those are minor given the schema already provides defaults and descriptions.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description adds value by explaining the `function` parameter's purpose ('scope to one function'), but does not add meaning beyond the schema for limit, format, or offset. This matches the baseline for fully self-documenting schemas.

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 graph's explicit comprehension frontiers', then enumerates concrete examples (unresolved calls, dynamic/reflective runtime behavior, parser/compiler diagnostics). This distinguishes the tool from siblings like coverage_map or scan, which sound related but are not the same operation.

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 tells the agent when to call it: 'to gauge how much of an answer is trustworthy', and gives scoping guidance: 'scope to one `function` or survey the whole graph'. It does not name alternatives or state when not to use it, but the context is clear enough 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool is an analysis operation, not a mutation ("not a registry mutation"), and that results are "evidence with confidence," which is useful context. It does not describe failure modes, confidence thresholds, or whether graph state is required.

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 two tight sentences with no filler. The first sentence states the operation and scope, and the second adds a useful behavioral qualifier about evidence-based output versus mutation.

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 conveys the core behavior and output nature, but with no output schema or annotations, it leaves significant unknowns such as return shape, confidence format, and graph prerequisites. Enough context is given for basic selection, but not full call confidence.

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 only 33%, and the description does not explain `function`, `limit`, or `format`. The prose clarifies the purpose but not the meaning of any parameter beyond the obvious requirement of a function symbol. It therefore fails to compensate for the low 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?

Uses a specific verb, "Infer", with a clear resource, "wrapper semantics," and enumerates meaningful role categories (allocator, deallocator, I/O, validator, forwarding call). It is distinct enough from siblings like callees or callers because it targets high-level wrapper semantics, though it does not explicitly name a sibling alternative.

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 the intended use case: derive wrapper semantics from graph evidence, and it explicitly excludes registry mutation, which reduces ambiguity. However, it does not state alternative tools to prefer in other scenarios or dependencies like whether the graph must be loaded first.

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