CodeAtlas

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

With no annotations, the description carries the full burden and does well: it discloses that results are capped, that uncertainty and index versions are reported, that budgets auto-adapt to change risk/fanout, that token_budget overrides this, and that the tool is read-only ('Does not run tests or modify Git'). It omits permission/index prerequisites, which keeps it from a 5.

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

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

The purpose and return contents are front-loaded in the first sentence, and every subsequent clause adds distinct information. It is dense and slightly run-on with mid-sentence semicolons, but there is very little wasted text.

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?

An output schema exists, so return-value detail is not required, and the description still covers comparison modes, budget behavior, and the read-only guarantee. Given 8 undocumented parameters, the definition is not fully complete, but it is adequate for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0% across 8 parameters, and the description only compensates for a subset: 'comparison' allowed values (working/staged/branch), base_ref's relationship to merge_base, and token_budget's override behavior. depth, max_files, max_symbols, and include_untracked remain undocumented anywhere, leaving real 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?

States a specific verb+resource: a Git-diff blast-radius analysis returning changed/removed symbols, transitive consumers, config/schema dependencies, and candidate tests. An agent can tell what it produces. However, it never differentiates itself from close siblings like 'impact' or 'task_context', so routing between them still requires inference.

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 explains the 'comparison' modes and how merge_base pairs with base_ref, which implicitly guides which mode to pick, and states 'Does not run tests or modify Git'). But there is no explicit when-to-use, when-not-to-use, or named alternative tool, so the agent must infer the workflow context on its own.

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 disclose meaningful behavior: a state transition to FIXING, a file-snapshot side effect, and a return of 'level-1 context'. However, it says nothing about permissions, whether claiming is exclusive/locking, reversibility, or error conditions (e.g., claiming an already-claimed issue).

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-loaded with the primary action and followed by the downstream consequence and return shape. No filler, though the parenthetical '(state FIXING)' could be tightened.

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?

An output schema exists, so return values need not be spelled out, and the description does link to verify_snipe and disclose the state change and snapshot. But for a workflow/mutation tool with zero annotation coverage and fully undocumented parameters, the omission of id/agent semantics and side-effect caveats leaves a meaningful 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 0% across two parameters, and the description never mentions 'id' or 'agent'. The agent must infer that id identifies the issue and that agent is an optional owner name, which is a real gap the description should have closed.

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

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

States a specific verb+resource ('take ownership of an issue') and a concrete side effect (snapshot its files) plus the resulting state (FIXING). It also positions itself relative to verify_snipe, so an agent can tell it apart from the other snipe tools. Slightly jargon-laden ('level-1 context', 'patch surface') but the core action is unambiguous.

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

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

The description frames the when: claim an issue to move it into FIXING and enable verify_snipe to measure the patch surface, implying this is the entry point of a fix workflow. It does not state exclusions or name a competing alternative explicitly, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It describes the output content (imports, dependents) but says nothing about mutation, permissions, side effects, or rate limits. For a read-oriented analysis tool this is less critical, but with zero annotations the description should confirm it's a read-only inspection operation.

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

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

The description is a single, efficient sentence that front-loads the key information (file-level imports, external packages, importers, dependents). It wastes no words but could be slightly more explicit about its scope versus 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?

The tool has an output schema, so return values need not be described. However, with no annotations and an undocumented 'path' parameter, the description is incomplete for a tool that likely expects a valid file path and may have behavioral nuances (e.g., only analyzing indexed files). It leaves the agent guessing about prerequisites.

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

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

With only one parameter ('path'), the schema description coverage is 0% and the parameter has no description in its schema. The tool description does not explain what 'path' should point to—a file, directory, or repo-relative path—nor does it indicate whether the path is required to be within the repository. This gap could easily cause invocation errors.

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

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

The description clearly states this is a dependency analysis tool covering file-level imports, external packages, importers, and transitive dependents. It's a specific verb-less noun phrase but conveys the resource (dependencies) well. It doesn't explicitly differentiate from the sibling 'relationships' tool, which could cover similar dependency territory.

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 when-to-use guidance or mention of alternatives. The description lists what the tool returns but provides no context on when to choose this over 'relationships', 'module_graph', or 'impact'. The agent must infer usage from the name and siblings alone.

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 disclosure burden. It implies a read-only operation via "read this instead of the file" and describes returned content, but never explicitly states side-effect-free status, cost, or whether private symbols are hidden by default.

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 short sentences, front-loaded with the resource and output contents, ending with the actionable selection instruction. Zero waste.

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

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

An output schema exists, so return values need not be explained, and the description adequately conveys scope. The one gap is the undocumented boolean options, which matter for correct invocation but are minor relative to the overall completeness.

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

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

Schema description coverage is 0% for all three parameters, and the description only loosely gestures at imports (related to show_imports) while saying nothing about include_private or the required path format. The optional flags remain undocumented in both schema and prose.

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

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

States a specific resource (classes/functions/methods in a file) and enumerates the exact payload (line ranges, signatures, reference counts, imports and importers), which cleanly separates it from siblings like repo_map, symbol_source, and grep.

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?

"Read this instead of the file" gives explicit when-to-use guidance. It does not name competing siblings such as grep or symbol_source, so the routing is clear but not exhaustive.

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

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

No annotations are provided, so the description carries the behavioral burden, and it does disclose the kinds of results returned and that filtering is supported. However, it says nothing about read-only nature, result volume/default limit behavior, ordering, or whether findings are cached/stale relative to the index.

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?

A single, dense sentence with the enumerations front-loaded and no filler. Slightly list-heavy, but every term 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?

An output schema exists, so return-value explanation is not required. Still, for a 3-parameter tool with zero schema descriptions, the description leaves 'limit' undocumented and offers no usage routing against sibling tools, which is a meaningful 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 0% for all three parameters, so the description must compensate. It clarifies that 'code' is a prefix match (a real semantic addition) and that 'path' is a filter, but it entirely omits the 'limit' parameter and its default of 100.

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 concrete resource (static findings from the index) and enumerates the specific finding categories (TAG_TODO/TAG_FIXME/TAG_BUG, EMPTY_CATCH, SWALLOWED_EXCEPTION, BARE_EXCEPT), which lets an agent distinguish it from grep or find_symbols. It stops short of a full verb framing and does not explicitly say how it differs from the sibling grep tool.

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

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

'Filter by code prefix or path' implies the two filtering modes, but there is no guidance on when to prefer this over grep (raw text search) or programming_patterns. The agent must infer that this returns pre-indexed static-analysis findings rather than arbitrary matches.

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 burden. It discloses the matching order (exact, prefix, substring, fuzzy CamelCase) and filter semantics, which is useful behavioral context. However, it omits limit behavior, result ordering, and any performance or permission notes.

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 waste. The core action is front-loaded, followed by matching strategy and filter details. Every phrase 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 an output schema exists, return values need not be explained. The description covers the core search and filters, but lacks guidance on usage versus alternatives and omits `limit` semantics. For a search tool with no annotations, this is adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly enumerates allowed `kind` values and explains `path` as a substring filter, and implies `query` is the name to search. The `limit` parameter (default 25) is not described at all, leaving one of four parameters undocumented.

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

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

States a specific verb (Find) and resource (definitions by name), and describes the matching strategy (exact, prefix, substring, fuzzy). However, it does not distinguish this tool from siblings like `symbol` or `grep`, which an agent would need to choose correctly.

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?

No explicit when-to-use or when-not-to-use guidance is given. The description implies it is for name-based symbol search but offers no alternatives or conditions for selecting it over other search tools like `grep` or `symbol`.

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 burden. It discloses the lazy, progressive-depth behavior and what each level returns, which is useful, but it omits safety properties (e.g., read-only), authentication needs, performance implications, or side effects.

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

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

The description is compact and front-loads the key idea ('Lazy context for an issue') before listing levels. It uses some terse jargon ('suspect', 'task_context') but avoids filler.

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

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

The output schema covers return values, and the level semantics are well described. However, the description leaves the required id parameter underexplained and provides no guidance on when to choose this tool over related context tools, leaving gaps for a complex multi-level retrieval operation.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly documents the meaning of the level parameter (0–6 with per-level outputs), but the required id parameter is only implicitly described as an 'issue' identifier and lacks explicit semantics.

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

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

The description states a specific resource (context for an issue) and details the progressive levels of information returned. It is clear enough for an agent to understand the tool's purpose, but it does not explicitly distinguish this tool from its many context-related siblings beyond a passing reference to task_context at level 6.

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 'Climb only as high as needed' gives clear guidance on selecting the level parameter, and the level-by-level mapping describes what each level provides. However, it does not state when to prefer this tool over alternatives like task_context or change_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 carries the full burden. It usefully discloses 'smart case' matching and that files must be indexed, but does not explicitly state that the operation is read-only or describe indexing prerequisites or rate/output 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?

Three short sentences, front-loaded with the core action and followed by parameter examples and usage guidance. Every sentence adds distinct value.

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

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

An output schema exists, so return values need not be described. The description adequately covers the main search behavior and glob parameter, though the undocumented limit parameter and lack of indexing prerequisites keep it from being fully complete for a 3-parameter search tool.

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

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

Schema description coverage is 0%, so the description must compensate. It gives helpful glob examples ('*.ts' or 'backend/*') and indicates the pattern is regex, but does not explain the limit parameter or provide more pattern syntax detail.

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 (regex search) and resource (indexed source files), and distinguishes itself from symbol-index siblings by noting it finds strings, config keys, and dynamic names the symbol index cannot see.

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?

Clearly identifies the use case: strings, config keys, and dynamic names not visible to the symbol index. It implies the alternative (symbol lookup) but does not name a specific sibling tool or provide explicit 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?

No annotations are provided, so the description must carry the full behavioral burden. It does not state whether the operation is read-only, whether it requires permissions, how it computes results, or any other behavioral trait. It only lists output categories.

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 short, front-loaded list of hotspot types, so it is concise. However, it is a sentence fragment rather than a structured statement, and it omits necessary context, making it under-specified rather than optimally concise.

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

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

An output schema exists, so return values need not be described, but the description still lacks essential context: what the tool does, when to use it, and what the limit parameter controls. It provides only a partial view of the tool's purpose, leaving significant gaps for an agent to call it correctly.

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

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

The schema has one parameter (limit) with 0% description coverage, and the description does not mention it at all. With no other source of meaning, the parameter's purpose and effect are entirely undocumented.

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 lists the categories of hotspots (complex functions, large files, PageRank symbols, import cycles), which conveys the tool's focus. However, it lacks a clear verb or resource statement (e.g., 'Find' or 'List'), leaving the action ambiguous. It is more specific than a tautology but does not fully distinguish from siblings like repo_overview.

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?

No when-to-use guidance, no alternatives mentioned, and no context on when this tool is preferable to other analysis tools. The description only states what it returns, not when an agent should invoke 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?

No annotations are provided, so the description must carry the full behavioral burden. It mentions the computed outputs but does not state whether the tool is read-only, when it performs heavy computation, or whether it requires permissions—leaving key behavioral traits undisclosed.

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 zero waste. The core purpose is front-loaded, followed by a concise usage condition.

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 0% schema coverage and no annotations, the description is adequate for purpose and usage but incomplete for parameters (missing path) and behavioral context. The output schema exists, so return values need no explanation.

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

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

Schema description coverage is 0%, so the description must explain all three parameters. It hints at 'symbol' (name) and 'depth hops' (depth) but completely omits the 'path' parameter and offers no format details for any of them.

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

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

The description states a specific concept ('Blast radius: transitive callers of a symbol') and its outputs ('affected files and tests'), clearly distinguishing it from siblings like references or dependencies. The verb is implied but the resource and scope are 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 gives a clear when-to-use statement ('Run before changing a signature or behaviour'), which provides actionable context. However, it does not name alternatives or specify when not to use it, leaving some room for 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, the description carries the full behavioral burden. It usefully discloses the auto-update background process and that a forced re-scan is normally unnecessary, but says nothing about cost, duration, blocking behavior, idempotency, or required permissions for a potentially expensive operation.

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

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

Two tight sentences, front-loaded with the core action followed immediately by the scoping caveat. No filler; every clause adds usable information.

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

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

An output schema exists, so return values need no explanation. For a one-parameter, non-required tool the description is nearly complete, missing only cost/latency expectations that would help an agent decide whether to trigger 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 description coverage is 0%, so the description must explain the lone parameter, and it does: it distinguishes the default incremental behavior from full=True and states when the full flag is warranted. The default (false) semantics are only implied rather than stated.

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 (re-scan) and resource (repository) with a clear modifier ('force'). It is reasonably distinct from the sibling index_status, which reports rather than rebuilds, but the description never names or contrasts an alternative, so differentiation is inferred.

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 condition for use ('use full=True after changing .gitignore or if results look stale') and an implicit when-not ('the index already auto-updates on file changes'). No sibling tool is named as an alternative, but the routing guidance 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?

No annotations are provided, so the description bears the full behavioral burden. It enumerates returned health fields, which implies a read-only informational tool, but it does not explicitly state read-only safety, side effects, permissions, or rate limits.

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

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

The description is a single front-loaded sentence that efficiently lists the key status components. Every part earns its place 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?

Given the zero-parameter schema and the existence of an output schema, the description is nearly complete for understanding what the tool reports. It could still add when-to-use context, but return-value details are appropriately left to the output schema.

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

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

The tool takes no parameters, so there are no parameter semantics for the description to clarify. Per the calibration rule, zero parameters corresponds to a baseline score of 4.

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 resource and scope: 'Index health' followed by specific health dimensions such as file/symbol counts, watcher state, dashboard URL, and last update time. It does not explicitly distinguish itself from siblings like repo_overview or impact, but the purpose is immediately understandable.

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 no guidance about when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. Usage is only implied by the name and status-like content.

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 disclosure burden. It usefully states that indentation is matched and that the edit is parse-validated before writing, which is real behavioral context beyond the schema. However, it says nothing about permission requirements, rollback, or what force and dry_run actually change at runtime.

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?

A single dense sentence plus a short validating clause. The anchor constraint is front-loaded and every word earns its place with no filler.

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

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

An output schema exists, so return values need not be explained, and the core insert semantics are covered. But for a mutation tool with zero annotation coverage and two opaque control parameters (force, dry_run), the description leaves meaningful gaps an agent would need to guess at.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It documents the where values ('before'|'after'), which is the only place that enum is expressed since the schema has no enums, but path, force, and dry_run are completely unexplained despite being safety-relevant.

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 (Insert), resource (new_text on its own lines), and anchor (before/after an existing symbol). An agent can distinguish it from replace_symbol or rename_symbol by behavior, though the description never names those siblings explicitly.

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

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

Usage is implied by the anchor semantics (insert relative to a symbol), but there is no explicit when-to-use guidance, no mention of when to prefer replace_symbol/rename_symbol, and no indication of when force or dry_run should be used.

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. It discloses that results are 'indexed source files' and include language/line/symbol counts, which implies a read-only index query rather than a filesystem scan. However, it does not state permissions, pagination behavior, or what happens with defaults, so important safety and operational context is missing.

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

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

The definition is a single front-loaded sentence with no filler. It states the action, resource, scope, and returned metadata efficiently. Every phrase 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?

An output schema exists, so the description need not explain return values in detail. For a two-parameter list tool with no annotations and 0% schema description coverage, it is minimally adequate: it states scope and counts but omits limit/pagination semantics and sibling routing.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It maps conceptually to the 'prefix' parameter by saying 'under a path prefix', but it never explains 'limit', its default of 300, or the empty-prefix default. Only partial compensation is provided.

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: 'List indexed source files'. It also adds scope ('under a path prefix') and fields returned ('language, line and symbol counts'). Sibling differentiation is absent: it does not explain how it differs from repo_map, file_outline, or other listing/indexing 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?

It gives an implicit context for use ('under a path prefix') but no explicit when-to-use, when-not-to-use, or alternative tools. An agent must infer from the name and siblings when this is the right tool. No prerequisites or routing guidance are provided.

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

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

With no annotations, the description carries the full burden but only states what the output represents. It does not say whether this is a read-only query (implied), how aggregation collapses edges, or what happens with sparse graphs.

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?

A single front-loaded sentence with no filler; the resource and aggregation rule come first. It is appropriately sized, though the brevity costs it parameter and usage detail.

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?

An output schema exists so return values need not be documented, and complexity is low. However, with no annotations and zero schema coverage, the unmentioned min_edges parameter and undefined depth semantics leave the definition short of what an agent needs to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It hints at 'depth' via 'aggregated at the given path depth' but never defines depth values, and min_edges is not mentioned at all, leaving half the parameters unexplained.

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 gives a specific verb-like concept (directory-level import graph) plus scope: modules depending on modules, aggregated at a path depth. It is clearly readable, though it does not explicitly contrast itself with siblings like dependencies or relationships.

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

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

There is no guidance on when to use this instead of dependencies, relationships, or program_map-type tools, and no prerequisites or exclusions. The agent must infer the use case purely from the phrase 'import graph'.

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 partially meets it by enumerating the returned payload (problem, evidence, suspect symbol with confidence, related symbols, context cost, risk, verification tests) and the prioritization policy. It never states whether the call is read-only or whether supplying an agent id claims/locks the item, nor whether repeated calls without an agent return the same item — a meaningful gap for a tool whose parameter exists to prevent collisions.

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-loaded with the selection rule and followed by return contents and the one parameter's usage. Dense but every clause carries information; no filler or restated boilerplate.

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?

One optional parameter and an existing output schema mean return-value documentation is a bonus rather than a requirement, and the description still summarizes the payload. The remaining hole is the side-effect profile — whether calling this reserves or locks a snipe — which an agent coordinating with claim_snipe and verify_snipe would want before calling.

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

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

Schema description coverage is 0% for the single 'agent' parameter, so the description must compensate, and it does: it explains the value type (a stable id) and the reason it exists (so several agents never pick the same item). It does not say whether the id is arbitrary or must match a registered agent, which is the only missing detail.

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?

Names a specific selection operation ('the highest-value isolated issue to fix next') and states the tie-breaking rule (own in-progress snipe first), which separates it from siblings like snipe_list and snipe_board. The domain term 'snipe' is never defined, but the surrounding clause makes the resource clear enough to invoke correctly.

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 one explicit usage rule ('pass agent="<stable id>" so several agents never pick the same item'), which is genuine when-to-use guidance for concurrent callers. It never states when NOT to use it or names an alternative tool for browsing versus picking, so an agent comparing next_snipe to snipe_list or claim_snipe must infer the distinction.

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. It does disclose useful traits: results carry syntax evidence and confidence, and catalogue=True avoids source scans (a cost/behavior distinction). It omits the read-only/safety profile, how pagination behaves, and what happens when filters match nothing.

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, and the core capability is front-loaded before the filtering/catalogue clause. The second sentence is somewhat dense with multiple clauses, which keeps it from a perfect score.

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

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

An output schema exists, so return-value documentation is not required. But for a 6-parameter tool with 0% schema coverage and no annotations, the agent still lacks guidance on pagination (limit/offset) and the token_budget control, leaving real gaps.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It meaningfully explains path, pattern, and catalogue semantics, but leaves limit, offset, and token_budget entirely undocumented in both places, so it covers only about half the 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 names a specific verb+resource ("Explain 12 programming patterns") and adds scope ("at actual source locations, with syntax evidence and confidence"), which clearly separates it from sibling analysis tools like grep, findings, or file_outline. It stops short of explicitly naming an alternative, so it is clear but not fully sibling-differentiated.

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?

"Filter by file/path and pattern ID; catalogue=True lists the supported concepts without source scans" gives concrete usage direction for the catalogue path and for filtering. However, there is no explicit when-not guidance against sibling tools (e.g. grep for raw text search) and no stated prerequisites, so usage is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the return grouping (by file, with line numbers and enclosing symbol), the pagination contract (true total, count shown, next offset), and the accepted kind categories. It omits permission/auth considerations, but for a read-only style query that is minor.

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 dense sentences, front-loaded with what is returned and followed by the scoping rule and pagination behavior. Every sentence adds information; nothing is padded.

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

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

An output schema exists, so return formatting need not be described, yet the description spends most of its length on return shape while leaving limit and exclude_tests unexplained. For a 6-parameter tool with zero schema coverage, coverage is partial.

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

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

Schema description coverage is 0% across six parameters, so the description must compensate. It explains path's scoping effect, enumerates kind values (call | new | arg | ref | import), and clarifies offset's continuation role, but name, limit, and exclude_tests are left undocumented.

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: it locates every place a name is used, grouped by file with line numbers and enclosing symbol. That is clearly distinguishable from siblings like symbol or find_symbols, though the differentiation from them is left implicit.

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 explains one usage nuance -- that supplying path (or a qualified name) pins a single definition so only matching references are listed -- which implies when to use the filtered mode. However, it never states when to reach for this tool over alternatives like symbol, dependencies, or relationships.

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

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

With no annotations, the description carries the full burden, and it does add genuinely useful behavior: pagination and inclusion of unresolved local targets. But it omits whether this is a read-only query, whether results are cached, and how results are ordered, leaving meaningful behavioral gaps for a 6-param 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?

Compact and front-loaded: the core semantics and the direction contract come first, and pagination is mentioned last. No wasted sentences, though it is dense enough that a beginner might miss the kind/path semantics.

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?

An output schema exists so return values need not be described, which the description correctly does not attempt. Still, for a 6-parameter query tool with 0% schema coverage and no annotations, key params (kind, path, token_budget) and the relationship to sibling tools are left unexplained, making it only minimally 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 description coverage is 0%, so all six params are undocumented by the schema. The description explains direction values (in/out) and implies pagination via limit/offset, but leaves kind, path, and token_budget completely undefined, compensating for only a fraction of the gap.

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

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

The description names a specific resource class (code/config/schema dependencies) and even defines the source/target consumption semantics, which is more than a restatement. However it never distinguishes itself from the sibling tool 'dependencies' or 'references', so an agent cannot tell which of the overlapping relationship tools to pick from the text 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?

The direction=in/out wording implies a usage pattern, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings (dependencies, references, module_graph). The agent must infer the routing decision.

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 safety burden. It discloses that only identifier nodes are changed, strings/comments/same-named symbols elsewhere are untouched, and ambiguous references are listed and skipped. It also explains the default dry_run behavior. Minor gap: no mention of required permissions or reversibility.

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, tightly written, front-loading scope constraints and then the dry-run workflow. 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?

An output schema exists, so return values need not be described. The description covers the tool's behavior, safety defaults, and edge-case handling (ambiguous references, non-identifier nodes). It is nearly complete for a rename tool, though additional parameter semantics would strengthen 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 0%, so the description must compensate. It explains the dry_run parameter's default and workflow, but does not describe name, new_name, path, or include_tests semantics. Given five parameters and zero schema descriptions, more parameter detail would be expected, but the dry_run guidance is critical and well-covered.

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 (rename) and resource (symbol at its definition and every reference that resolves to it), and clarifies the exact node types affected, which distinguishes it from siblings like replace_symbol and references.

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

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

Provides clear guidance on the dry-run workflow: review the plan, then call again with dry_run=False. However, it does not explicitly say when to prefer this tool over replace_symbol or impact, leaving some alternative selection to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the parse-first/refuse-on-syntax-error safety check, the force override, the concurrency guard via expected_hash, an immediate re-index side effect, and dry_run preview. It lacks any note on permissions/scope-of-file targeting, but the behavioral disclosure is unusually rich for a mutation 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?

Dense but front-loaded, leading with the core action and following with safety, concurrency, and return behavior. Each clause adds distinct information, though the packed phrasing slightly hurts scannability.

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?

An output schema exists, yet the description still notes it returns old text + hashes. Combined with coverage of safety, concurrency, preview, and re-indexing, this is nearly complete for a complex mutation tool; only the path parameter's role is unexplained.

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

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

Schema coverage is 0%, so the description must compensate; it explains new_text, force, dry_run, and expected_hash (tying it to 'old_hash from a previous call') clearly. It omits any explanation of the path parameter, which is the one gap for a 6-param tool.

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+scope: replacing exactly one declaration at its syntax-tree span, including decorators/export, with re-indented text. An agent can distinguish it from siblings like rename_symbol or insert_code without opening any schema.

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

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

Provides operational conditions (dry_run previews, force overrides the safety check, expected_hash guards concurrency) but never states when to choose this tool over siblings such as rename_symbol, insert_code, or symbol-based edits. Usage 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?

No annotations exist, so the description carries the full burden and does well: it discloses the truncation rule (nothing cut unless token_budget is given) and the ranking behavior, which are genuine behavioral traits. It omits any auth/permission or cost context, but for a read-style map tool this is solid 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?

Dense but front-loaded: the opening sentence defines the output, and each subsequent clause adds the truncation rule, ranking-bias semantics, and usage directive. No filler, though the single packed paragraph is slightly heavy.

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?

An output schema exists, so return values need not be explained, and the description covers output content, ordering, truncation, and focus behavior adequately for a moderately complex tool. The only gap is the unexplained exported_only parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It explains token_budget (truncation to top-ranked that fit) and focus_paths/focus_names (bias ranking toward current work), adding real meaning, but says nothing about exported_only, leaving one of four parameters undefined anywhere.

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

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

States a specific verb+resource: it lays out exactly what the map contains (files with classes/methods and function signatures, ordered by PageRank). This is clearly distinguishable from siblings like list_files and file_outline without opening either schema.

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

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

"Use it instead of listing or reading files" gives a clear when-to-use directive against the general alternative actions. It stops short of naming specific siblings (list_files, file_outline, repo_overview) and offers no explicit when-not-to-use condition, so it's strong but not fully routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the useful trait of a bounded output size (~400 tokens), which is a real behavioral signal beyond the schema. But it says nothing about read-only safety, side effects, or performance for a tool with no annotation coverage.

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

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

A single compact sentence with the call-to-action front-loaded and a tight comma-separated inventory. Every clause earns its place, though the trailing token estimate is slightly tacked on.

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?

An output schema exists, so return values need no narrative, and with zero params and 100% schema coverage the structured fields are complete. The description adds the orientation role and size hint the agent needs to call it appropriately.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly omits parameter discussion.

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 orientation verb ("Start here") plus the concrete contents it returns: languages, top directories, hub files, entry points, key symbols, finding counts. This tells the agent exactly what resource it gets. It does not differentiate itself from closely related siblings like repo_map or index_status, so it stops short of a 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?

"Start here" is an implied ordering cue for a first-pass orientation, which gives some usage context. However, no alternative is named and no conditions for when-not-to-use it are given, leaving routing against siblings like repo_map or file_outline to inference.

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

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

No annotations are supplied, so the description carries the full burden. It discloses the status mutation ('Marks it BLOCKED / INVESTIGATE with the reason') but says nothing about permissions, reversibility, whether the snipe must be claimed, or any other side effect; for an unannotated mutation this is thin.

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 short sentences with no wasted words, and the stop condition is front-loaded. However, the action is buried in the second sentence and the colloquial 'nobody wanders for 40 minutes' adds color but not operational 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?

Given no annotations, two required parameters with 0% schema descriptions, and a mutation operation, the description should explain the id, reason, and effect on the snipe. The output schema covers returns, but the invocation semantics and behavioral guarantees are incomplete.

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

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

Schema coverage is 0%, and the description mentions only 'the reason' without defining its format or role. It says nothing about the required 'id' parameter (presumably the snipe identifier), so it leaves most parameter meaning to the schema titles alone.

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

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

The description conveys an abort-like action ('Stop condition', 'Marks it BLOCKED / INVESTIGATE') and the trigger, but it never defines 'snipe' or clearly states that it aborts a claimed snipe task. It also does not differentiate from siblings like verify_snipe or snipe_update, so an agent must infer the resource.

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 conditions ('the fix stopped being a snipe') with examples (schema migration, public API change, many modules). It stops short of naming when not to use it or pointing to an alternative tool, so not a 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully clarifies that this logs findings rather than fixing drive-by issues and gives an evidence format, but it does not state persistence, permissions, or what side effects recording a snipe has.

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 short and front-loaded: it states the action first, then the evidence format, then the log-not-fix rule. Every sentence adds useful information 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?

For a five-parameter mutation/logging tool with no annotations and no schema field descriptions, the description is incomplete. It covers the core purpose and evidence format but omits several parameter meanings and behavioral details needed for confident invocation, even though the output schema reduces the need to explain return values.

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

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

Schema description coverage is 0% for five parameters. The description explains kind=issue/opportunity and evidence as 'path:line' or symbol names, but it leaves problem, suspect, and priority largely unexplained, so the agent still lacks semantics for most inputs.

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: record a defect or dormant improvement, with kind values issue/opportunity. It distinguishes the two record types clearly, though it does not explicitly differentiate this tool from sibling snipe_* tools at a naming level.

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 implied when-to-use context and one when-not instruction: 'Do not fix drive-by findings; log them.' However, it does not name alternative tools or clarify when to call snipe_add versus snipe_report, snipe_scan, or other workflow siblings.

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

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

No annotations are provided, so the description carries full behavioral burden. It lists content categories but does not disclose whether the tool is read-only, requires authentication, has side effects, pagination, or rate limits; only the word 'list' weakly implies retrieval.

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?

It is a single concise fragment with no filler, and the core 'ready-to-snipe list' is front-loaded. However, the comma-separated content list is structurally rough and under-specified rather than a complete, well-formed statement.

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?

An output schema exists, so return-value explanation is not required in the description. Still, with numerous snipe_* siblings and no annotations, the description omits enough usage and differentiation context that an agent may struggle to select 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?

The tool has zero parameters and schema description coverage is 100%, so the schema is complete for invocation. Per the rubric, 0 params baseline is 4; the description does not need to explain 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 is a noun phrase listing board contents ('ready-to-snipe list', 'investigating', 'current work per agent', 'counts') rather than stating an action. An agent can infer it retrieves a dashboard, but the purpose is vague and does not distinguish it from sibling tools like snipe_list or snipe_item.

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?

No when-to-use, prerequisites, or alternative selection guidance is provided. The agent must guess whether to call snipe_board instead of snipe_list, next_snipe, or other snipe_* 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 carries the full burden. It usefully discloses auto-detection from package.json/pyproject when unset and the {file} templating of test_cmd, but says nothing about whether config persists, overrides existing values, or requires any permission.

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 verb+resource and uses examples efficiently. The trailing 'Stop-condition limits too.' is telegraphic and does not earn much, but overall the text is compact 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?

An output schema exists so return values need not be explained, but for a 7-parameter configuration tool with 0% schema coverage, six parameters are left entirely undocumented. The description is too thin to let an agent configure verification correctly.

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

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

Schema description coverage is 0% across 7 parameters. The description explains only test_cmd (template with {file}, auto-detected) and vaguely alludes to 'stop-condition limits'; lint_cmd, full_test_cmd, typecheck_cmd, test_timeout, max_patch_files and max_patch_symbols remain undefined in both schema 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?

States a specific verb+resource ('Configure verification') and names concrete settings (test_cmd, stop-condition limits), so the agent knows this writes verification configuration. It does not distinguish itself from the many snipe_* siblings, but the purpose 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?

No explicit when-to-use, prerequisites, or alternatives are given. The note that test_cmd is 'auto-detected ... when unset' hints at the omission behavior but does not tell the agent when it should call this versus letting defaults apply.

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 returns a 'full record' with evidence, candidates, factors, and notes, which implies a read-only retrieval operation, but it does not state permissions, side effects, or other operational constraints.

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

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

The description is very short and free of filler, with the returned content front-loaded after a colon. However, it is a sentence fragment rather than a complete, structured tool description, leaving key elements such as the action and parameter semantics unstated.

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?

An output schema exists, so return values need not be fully explained, but the description remains incomplete for an agent to invoke the tool correctly. With no annotations, 0% schema description coverage, and many sibling tools, it omits parameter guidance and selection context.

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

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

Schema description coverage is 0% for the single required 'id' parameter, and the description does not explain the parameter's format or meaning. The phrase 'one issue/opportunity' loosely implies the id identifies the entity, but the description adds almost no semantic detail beyond the bare schema.

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

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

The description identifies the resource ('one issue/opportunity') and some returned fields, but uses a noun phrase with no explicit action verb. It does not distinguish itself from siblings like get_snipe_context, snipe_list, or next_snipe.

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 when-to-use guidance, no prerequisites, and no alternatives named. The closest thing to usage context is the implied retrieval of a single issue/opportunity, which is not enough to tell an agent when this tool should be selected over related snipe 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 carries the full behavioral burden and supplies almost none: no statement that this is a read-only operation, no ordering or pagination behavior despite a limit parameter, and no mention of what the default (unfiltered) result 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?

Very compact and front-loaded, with each fragment attached to a parameter rather than padding. The telegraphic style costs a little clarity but 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?

An output schema exists, so return values need not be described, and three of four parameters are covered well. Still missing for a listing tool with a limit parameter: ordering, default result set, and pagination 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 0% — the schema only carries titles and defaults — yet the description supplies the allowed values for kind, state, and priority (including the exact state and priority tokens), which is meaning the agent cannot get from the schema. Only limit remains undocumented, keeping it short of a 5.

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

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

It states the verb and a generic resource ("List records"), then enumerates filter dimensions, so the agent knows it retrieves snipe records with filters. However "records" is vague and nothing distinguishes it from the many sibling listing tools (snipe_board, snipe_item, findings), leaving sibling selection to inference.

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 statement of when to use this over snipe_board, snipe_item, or next_snipe, and no prerequisites or exclusions. The filter values imply filtered listing but give no guidance on choosing 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?

With no annotations, the description carries the full burden. It discloses the transformation (each failure becomes an issue narrowed to a symbol), which is useful behavioral context. However, it omits side effects such as whether issues are persisted, whether authentication or repo context is required, and whether input is validated or modified.

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 action and followed by precise detail. Every clause earns its place, and there is no redundant or filler text.

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 annotations and 0% schema description coverage, the description covers the core action and parameter semantics but leaves gaps around prerequisites (e.g., repo context) and side effects (issue creation behavior). It is the minimum viable level for an agent to call the tool, but not fully 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 0%, but the description compensates well: it enumerates the allowed values for the source parameter (test, typecheck, lint, runtime) and describes the text parameter as the pasted failing output. This adds meaningful semantics beyond the bare schema.

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

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

The description clearly states a specific verb and resource: it ingests external evidence (failing test/typecheck/lint/runtime output) and converts each failure into an issue narrowed to a suspect symbol. This is distinct from sibling tools like snipe_add or snipe_scan, though it does not explicitly name or contrast with those 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?

There is no explicit when-to-use or when-not-to-use guidance. The description implies usage by describing the input format, but it never states prerequisites, alternatives, or conditions under which this tool should be preferred over manual issue creation.

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 burden and does so reasonably: it discloses that a static pass maps unresolved imports to issues while complexity/cycles/swallowed errors become dormant opportunities, that `run` executes a configured command, and that scanning happens automatically on save. It omits permission/rate-limit details but covers the important side-effect 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?

Front-loads the core action, then the no-`run` case, then the `run` case, then the automatic-scan note. Dense but every clause carries information; slight compression would help readability.

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 one-parameter tool with an output schema, the description covers modes, defaults, and side effects adequately. Return values need not be explained since an output schema exists, leaving little an agent needs that 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 0% for the single `run` parameter, so the description must supply its meaning — and it does, enumerating the accepted values ('tests'|'typecheck'|'lint') and describing the default no-run behavior. This meaningfully exceeds the bare schema.

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

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

States a specific verb and resource ("Scan for concrete problems") and distinguishes its two modes of operation. It is clear what the tool produces (issues and dormant opportunities), though it never explicitly contrasts itself with the closely related `findings` 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?

Explains the conditional usage well: without `run` it does a cheap static pass, and `run='tests'|'typecheck'|'lint'` triggers an actual command. It also notes automatic index-delta scanning on save. No explicit when-not or named alternative among siblings, but the mode selection 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?

With no annotations, the description carries the full behavioral burden. It indicates mutation ('Change', 'add') but does not disclose permissions, reversibility, partial-update semantics, whether note appends or replaces, or what happens when optional fields are omitted.

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?

A single front-loaded sentence with no filler. It efficiently lists the mutable fields and embeds the state enum, so every part 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 7-parameter mutation tool with no annotations and no schema descriptions, the description leaves critical gaps: the required id, the agent parameter, and mutation behavior. An output schema exists but does not compensate for missing input semantics.

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

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

Schema description coverage is 0%, so the description must compensate. It names state, priority, suspect, kind, and note, and usefully enumerates the allowed state values, but it omits the required id parameter and the agent parameter entirely and gives no formats for priority or note.

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 has a clear verb, 'Change', and lists multiple mutable fields, so the basic action is understandable. However, it never names the resource ('snipe') and does not differentiate this tool from siblings like claim_snipe, verify_snipe, or snipe_add, so it falls short of a 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?

There is no guidance on when to use snipe_update versus alternatives such as claim_snipe, verify_snipe, or snipe_abort. The description implies editing an existing record but gives no prerequisites, sequencing, or 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses what kinds of data are returned and how names can be formatted, but it does not mention permissions, side effects, error behavior, or performance characteristics. For a read-only lookup tool this is adequate but not rich.

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 core purpose, and every clause adds useful information. There is no redundancy or filler.

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

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

An output schema exists, so the description does not need to document return values in detail, though it helpfully lists the main categories. For a two-parameter tool with no annotations, the main remaining gap is explicit guidance on when to use this tool versus its many siblings.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains that name can be plain, qualified, or path:line, and that path= can be used to disambiguate, adding meaningful semantics beyond the bare schema. The exact expected format of path is still not specified, keeping it from a 5.

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

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

The description clearly identifies the resource ('one symbol') and lists the kinds of information returned: location, signature, doc, complexity, members, callers, callees. It is easy to distinguish from search-oriented siblings like find_symbols, but it does not explicitly name an alternative or state a verb, so it falls just short of a 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 gives one usage tip: use path= to disambiguate. It implies the tool is for retrieving comprehensive information about a single symbol, but it does not describe when to choose it over siblings such as find_symbols, symbol_source, or references, nor does it state any 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 no annotations, the description carries the full behavioral burden and only discloses that output includes line numbers and is cheap. It says nothing about failure modes (unknown symbol, out-of-range), what the optional `context`/`max_lines` parameters do behaviorally, or how a range target interacts with the symbol lookup.

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 short sentences, front-loading the resource and the cost rationale; nothing is wasted and the key constraint (range syntax) is tucked in parenthetically without bloating the text.

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?

An output schema exists so return values need not be described, but the tool has 4 undocumented parameters at 0% coverage and no annotations, and the description covers only one param plus a cost note. An agent still cannot confidently supply `context` or `max_lines`.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate. It clarifies only `target` (symbol name or path:start-end range); `path`, `context`, and `max_lines` are left completely unexplained in both schema 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 states a specific resource ('source text of one symbol') and even disambiguates the target format as a symbol or a path:start-end range. But it does not distinguish itself from close siblings like `symbol`, `grep`, or `file_outline`, leaving the agent to guess which retrieval tool to pick.

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?

'Cheaper than reading the file' implies a usage context — prefer this over reading the whole file — but there is no explicit when-to-use vs. other source-reading siblings, no exclusions, and no mention of when `symbol` or `file_outline` would be better.

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 and does well: adaptive budget by default, token_budget override, a per-item 'why' and expand handle, plus truncation and index version reporting. The ordering/ranking behavior is disclosed clearly. It stops short of stating idempotency or whether an index must exist first.

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?

Information-dense and front-loaded: the core purpose leads, then scope, budget behavior, and output traits. Every sentence earns its place, though the run-on structure packs several ideas into a single block.

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 retrieval tool with an output schema present, the description gives the agent a solid mental model: what is returned, how ranking works, how to scope, how to control budget, and what metadata accompanies results. The undocumented max_symbols is the only notable 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 0% for 5 parameters. The description explains scope (path prefix with an example), token_budget (override for adaptive budget), and implicitly include_source via 'with source for the strongest ones', but max_symbols (default 40) is never mentioned, leaving partial compensation for the coverage gap.

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

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

States a specific verb and resource: a single call to gather task-relevant symbols, source, tests, and config/docs, with the BM25/PageRank retrieval mechanism named. An agent can tell it apart from repo_overview or find_symbols, though it never names a sibling explicitly.

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

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

'One call to start a task' implies this is the task-entry point, which is useful framing. However, it never states when to prefer it over find_symbols, references, or repo_map, nor any exclusion. Usage is implied rather than stated.

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 carry the full behavioral burden. It describes the kinds of trigger relationships it detects, but omits essential traits such as read-only status, indexing requirements, performance characteristics, or how it handles unresolved symbols. This is a significant gap for a code-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 compact, front-loads the core purpose, and uses concrete examples without filler. It is slightly fragmented but every clause contributes to understanding the tool's scope.

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?

An output schema exists, so return values need not be explained, and the description adequately conveys the kind of trigger analysis performed. However, the lack of parameter semantics, usage guidelines, and behavioral transparency leaves the definition only minimally viable for correct invocation.

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

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

Schema description coverage is 0% and the description does not mention the required 'name' parameter or the optional 'path' parameter at all. The schema titles ('Name', 'Path') provide minimal hints, but the description adds no meaning beyond them, leaving the agent to infer that 'name' is the symbol and 'path' is a file path.

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 analytical purpose: identifying what causes a symbol to run, enumerating concrete trigger sources (route/event decorators, callback registrations, direct callers, owning class). It does not explicitly differentiate itself from sibling tools like references or dependencies, so it falls short of a 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 implies usage by framing the tool as answering 'what triggers what', which gives the agent a context for when to use it. However, it offers no explicit when-to-use guidance, no comparison to alternative tools, and no prerequisites or 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 no annotations, the description carries the full burden. It adds a safety warning about verifying before deletion, implying the tool is read-only and results are candidates rather than definitive. However, it does not state read-only behavior explicitly, nor does it describe potential limitations or output characteristics beyond what the output schema provides.

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 purpose, followed by a crucial caution. Every sentence adds value without redundancy.

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

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

The output schema exists, so return values need not be explained. The description adequately covers the tool's purpose and a key safety caveat, but it leaves parameter semantics entirely undocumented and does not fully compensate for the absence of annotations, leaving 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?

Schema description coverage is 0% for both parameters (limit, include_exported), and the description provides no information about their meaning or effect. The description fails to compensate for the schema's missing parameter documentation.

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 output type ('Dead-code candidates: functions/classes with no references anywhere'), making the resource and scope clear. It implicitly contrasts with related tools like 'references' by focusing on the absence of references, but does not name siblings explicitly.

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

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

It gives a clear workflow: use this to find dead-code candidates, then verify with triggers/grep before deleting. It lacks explicit when-not-to-use conditions or alternative discovery tools, but the guidance is actionable and context-rich.

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. It discloses level gating, PASS/FAIL state transitions, and abort on excessive blast radius, but it does not say whether the tool mutates state, requires authorization, or what 'SNIPE ABORTED' concretely does.

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 and packed into a single long sentence with semicolons. It avoids fluff, but the level and status mappings are hard to parse and would benefit from clearer structure.

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?

An output schema exists, so return values need not be explained. But with no annotations and 0% schema description coverage, the description should compensate by explaining the required id parameter and safety profile; it does not, leaving the invocation contract incomplete.

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

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

Schema description coverage is 0% for both parameters. The description explains that deep=True triggers the full suite, but the required id parameter is never defined, leaving half the parameters semantically undocumented.

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 gives a specific verb and resource: 'Evaluate outward from what you changed,' then enumerates the verification checks by level. It is clear what the tool does, but it does not differentiate this tool from sibling snipe/verification tools such as next_snipe or snipe_report.

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

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

It provides explicit conditions for each verification level: level 2 only if level 1 passed, level 3 only when deep=True or risk is high. It also maps outcomes to next states. However, it does not state when to use this tool instead of sibling tools.

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