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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns a bounded context (under 4096 code units), inlines seed definitions only when 40 lines or shorter, and reports exact omission counts. It doesn't mention performance or error behavior, but the key output characteristics 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 tight sentences: the first packs the output content and size constraint, the second gives the usage rule and alternatives. No filler words, though the first sentence is noun-heavy and requires careful parsing.

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 retrieval tool with a fully described schema and explicit safety annotations, the description covers purpose, scope, output bounds, and when/when-not. No output schema exists, but the size limit and omission counts are stated. It lacks detail on failure modes or response shape, which is acceptable given the structured coverage.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters with defaults, enums, and semantics. The description only broadly refers to 'seed definitions' and 'callers/callees' without adding syntax, format, or inter-parameter behavior beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb (retrieve/assemble) and resource (task context: seed definitions, callers/callees, test files) with a size bound and omission counts. It clearly distinguishes itself from siblings by naming ground and warp as alternatives for single symbols. The purpose is clear, though the quirky companion tool names and the dense phrasing slightly obscure it.

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 it ('once at the start of a change or review that spans more than one file') and when not to ('for a single known symbol use ground or warp instead'). This is exactly the kind of routing guidance an agent needs.

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

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

Annotations cover read-only, idempotent, non-destructive safety. The description adds output-format behavior: lean vs full inlining and defaults. It doesn't cover rate limits, auth, or failure modes, but for a read-only search this is adequate.

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

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

Front-loaded with the core purpose and output format, then parameter behavior. Some redundancy between the initial list and later detail, but overall tight and useful.

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

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

For a read-only search tool with full schema coverage and no output schema, this description covers purpose, output shape, parameter interactions, and a usage entry point. It lacks sibling differentiation, which is the main gap.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description explains the interaction between lean and full (lean=false inlines if <=40 lines or an 8-line excerpt; full=true inlines whole), which adds value beyond schema descriptions.

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

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

Clearly states it is a search tool that finds definitions by keyword or identifier, and adds specific behavior: it returns file:line, kind, definition span, and signature. The mention of route registration for frameworks distinguishes it from a generic text search.

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?

Tells the agent to start here when code location is unknown, which gives a clear use context. It doesn't explicitly compare to sibling tools like osnova_groundwork or osnova_outline, but the routing is strong.

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

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

Annotations already declare this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond them: the output budget (under 2048 code units) and the composition of the result (clusters, hubs, hotspots), plus the 'use once' sequencing constraint.

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 what the tool returns, then the usage rule. Every clause carries information; the size bound and the anti-pattern warning both earn their 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 read-only, zero-required-parameter summary tool with no output schema, the description covers purpose, scope, output composition and usage discipline, which is sufficient for correct invocation. It stops short of describing the shape or ordering of the returned map, which a description-only tool could mention.

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?

There is one optional parameter with 100% schema description coverage, so the schema already documents maxDirs and its default of 8. The description's reference to 'directory clusters' loosely matches the parameter, but adds no syntax or behavior beyond the schema; baseline 3 applies.

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

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

The description states a specific resource and its contents: a repository map of directory clusters, hubs and hotspots, bounded to under 2048 code units. It also distinguishes itself from the sibling osnova_outline by warning against following it with an outline of every directory.

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 triggering condition ('use once when the repository is unfamiliar') plus an explicit anti-pattern ('do not follow it with an outline of every directory'), which implicitly routes the agent away from osnova_outline. The alternative is described behaviorally rather than named by tool, so it stops short of the explicit routing a 5 requires.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description goes further by disclosing the 4096 code-unit selection budget and that omissions are exactly counted, which tells the agent output may be incomplete by design.

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 purpose before the usage instruction, and every clause carries information. The first sentence is dense and comma-embedded, which slightly slows parsing but wastes no 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?

With no output schema, the description must explain returns, and it does: definitions, signatures, line spans, and an omission count. Combined with annotations covering the safety profile and full schema coverage on the single parameter, an agent has what it needs to call this correctly.

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

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

Only one parameter, and schema coverage is 100% with the description 'Repo-relative file path'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 for full schema coverage applies.

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

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

States a specific verb and resource ('Outline: the definitions of one file') plus the exact output shape (signature and line span, selection by connectivity, 4096 code-unit budget, count of omitted). This is clearly distinguishable from the sibling tools that read, test, or warp code.

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 'Use instead of reading a whole file to learn its shape; read only the span you need afterwards,' which gives both a positive trigger and a follow-up workflow. It does not name which sibling implements the whole-file read, so the alternative is implied rather than routed.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds important behavioral nuance by clarifying that 'confirmed' means an indexed resolved edge, not runtime proof, and that it can surface omitted dependents. It doesn't describe output format, but no output schema exists, so this is a minor gap.

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 first sentence front-loads the core operation and classification outcomes; the second gives usage advice; the third defines 'confirmed.' It is slightly dense but every sentence contributes.

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

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

For a read-only verification tool with no output schema, the description covers purpose, the four classification outcomes, usage timing, and the meaning of 'confirmed.' It could specify output structure, but the agent has enough to invoke and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning and default. The description restates the core inputs (symbol and path:line sites) but adds no format or constraint details beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verification purpose: given a symbol and claimed call sites, it classifies each as confirmed, name match only, no call, or omitted indexed dependent. This is distinct from the sibling tools (which appear to be discovery/index tools), and an agent can tell immediately what the tool does.

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 'Use before declaring a caller list complete,' which gives one clear context, but there are no alternatives named and no explicit when-not-to-use guidance. For a tool whose siblings include likely related graph tools, more routing guidance would help.

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

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

Annotations already cover read-only, idempotent, non-destructive, and non-open-world traits. The description adds substantial behavioral detail: output truncation under 4096 code units with exact omission counts, cache indexing of baseRef trees, diff computation when none is given, and the limitation that a diff alone cannot show deleted symbols.

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

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

The description is three dense sentences that are front-loaded with purpose, followed by usage and caveats. Every sentence contributes, though the nested clauses make it slightly harder to parse than ideal.

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 change-impact tool with no output schema, the description covers what is returned (symbols and dependents, with omission counts), when to use it, how arguments behave, and key limitations. Annotations carry the safety profile, so the remaining context is sufficient.

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: no-argument behavior settles uncommitted changes against HEAD, diff alone compares only against the current index, and baseRef indexes a commit tree under the cache without checkout.

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 analysis: given a git diff, it computes touched symbols and indexed dependents at a depth, with output limits. It distinguishes itself from a plain diff by explaining index-based comparison, but it does not explicitly differentiate from sibling tools like osnova_tests or osnova_unreferenced.

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?

Usage is explicit: 'Use once after editing, before declaring done, to find callers the tests do not cover,' and no-argument behavior is defined. It lacks explicit when-not-to-use guidance and does not name alternative sibling tools for comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., so safety and idempotency are covered. The description adds valuable context beyond annotations: it explains the two-tier result structure, that an empty resolved tier is stated on its own line, that import-only files are leads not tests, and provides an important caveat about the limitations ('No indexed test is not proof of no test, and a listed test is not coverage'). It doesn't discuss rate limits or auth, but none are relevant here.

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 that packs a lot of information, but it's not front-loaded with a clear summary sentence. The purpose is buried after listing tier details. It could be better structured with a leading sentence stating the core function, then details. However, it is not overly 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?

Given the complexity of the tool (dual-mode, two-tier results) and the lack of an output schema, the description does a good job covering return semantics and caveats. It could be improved by explaining what happens when both parameters are omitted (since required parameters is 0), but it largely addresses what an agent needs to know.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds a bit of meaning by clarifying the mutual exclusivity ('Exactly one of symbols or file') and the tier interpretation, but it doesn't add new syntax or format details for parameters. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: finding indexed test files for given symbols across two tiers, and conversely listing symbols under test for a given file. It specifies the exact dual-mode behavior precisely. It does not distinguish this tool from its siblings (e.g., doesn't say why to use this over osnova_unreferenced or osnova_ground).

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 usage context: 'Use before editing to find the tests to run.' It also specifies the mutual exclusivity constraint: 'Exactly one of symbols or file.' However, it doesn't compare to sibling tools or state when NOT to use this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description builds on top of that with real operational detail: grouping by enclosing definition, dependency-based ranking, a 10-matches-per-group cap, a 50-group default that `limit` raises, and the guarantee that totals and omission counts are exact. The completeness guarantee in particular tells the agent it can trust pagination boundaries, which is exactly the kind of context annotations cannot express.

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, both front-loaded with the most important information (search semantics first, caps and completeness second). Every clause earns its place: the parenthetical about `limit` and the omission-count guarantee both change how an agent would call or interpret the tool. No filler, no restatement of the name.

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

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

There is no output schema, so the description carries the burden of explaining return shape, and it does so reasonably: groups, matches per group, default caps, and exact totals/omission counts. What is missing is the concrete structure of a returned group or match (fields, identifiers), but for a read-only search tool with fully documented parameters this is close to 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 100%, so a baseline of 3 applies and the schema already documents pattern, fixed, in, limit, and ignoreCase. The description goes one step further by clarifying that `limit` raises the *group* cap rather than the per-group match count, resolving an ambiguity in the terse schema text. That is a modest but genuine addition beyond the structured 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 states a specific verb and resource (text search with regex/literal matching over indexed text) and adds distinctive mechanics: results grouped by enclosing definition and ranked by dependents. That separates it from a generic search. It does not, however, name or contrast against any sibling tool (osnova_ground, osnova_outline, etc.), so the agent still must guess how it relates to the rest of the family.

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?

Usage is only implied: the agent can infer this is the tool for finding text occurrences in indexed code. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool for a different search style. For a search tool in a family of ten opaque siblings, more routing guidance would help.

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

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

The description adds substantial behavioral context beyond the annotations: it explains that results are sorted by file and line, describes what each result entry contains (unresolved same-name call site counts, test-file sites, identifier mentions), details the exclusion rules for entry points, and warns about the interpretation limit. This goes well beyond the readOnly/idempotent annotations. However, it doesn't discuss pagination behavior or performance characteristics.

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 efficient — it front-loads the core purpose and packs substantial qualification, exclusion rules, and interpretation caveats into a compact span. There's minimal waste, though the parenthetical enumerations make it slightly heavy to parse in one pass.

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

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

Given the complexity (a code-analysis query tool with nuanced semantics), no output schema, and the need to explain what 'unreferenced' means and its limitations, the description covers the essential ground: output format, exclusion rules, parameter effects, and a crucial interpretation caveat. It could be improved with a brief note on pagination or typical use case, but the core is solid.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds meaning by explaining why certain kinds are excluded by default ('constants, types and interfaces receive no edges, so asking for them lists nearly all of them') and clarifying that 'the omitted count is exact' for the limit parameter. This enriches understanding beyond raw schema text.

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

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

The description states a specific resource ('unreferenced candidates: definitions with no resolved call or reference edge from outside their own body in a non-test file') with clear precision about what is and isn't included. The sibling tools have opaque names (groundwork, outline, warp, etc.), and while no sibling is named explicitly, the semantic specificity of 'unreferenced candidates' makes the tool's purpose unambiguous.

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

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

The description provides strong contextual guidance: it clarifies what constitutes an entry point that's never listed, explains the includeExported flag's purpose, and includes a caveat ('Candidates only: no indexed caller is not proof of no caller'). However, it doesn't explicitly name alternative tools or state when an agent might prefer an alternative approach. The guidance is about interpretation, not tool selection.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so safety is covered. The description adds genuinely useful behavioral context beyond annotations: the exact return format (file:line), the accepted input forms, and a crucial caveat that an empty list means 'no indexed caller, not proof that none exists.' It does not describe pagination or the non-full mode summary behavior, which the schema handles.

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 sentences, front-loaded with the core purpose, then usage, then an important caveat. Every sentence earns its place with zero filler.

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

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

For a read-only query tool with full schema coverage and no output schema, the description provides everything needed: what it returns, how to call it, when to use it, and a critical interpretation caveat about empty results. 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 coverage is 100%, so parameters like full, depth, and direction are already fully documented in the schema. The description reinforces direction and accepted symbol formats but adds little beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Opens with 'Call graph:' and states both directions (who calls a symbol, what it calls) with exact output format 'file:line'. A specific verb+resource that is immediately distinguishable from sibling tools like osnova_outline or osnova_ground.

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

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

Explicit when-to-use: 'Use before changing a signature or deleting code.' Names the default direction inline. This directly ties the tool to a developer workflow, leaving little ambiguity about when to invoke it.

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