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

Annotations only declare readOnlyHint=true; the description goes further by disclosing output ordering ('removed/signature changes with callers outside the diff first'), tier grouping, and a hard output budget ('<= 2000 tokens'). This is meaningful behavioral context beyond the safety hint, though nothing is said about how tiers are defined.

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

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

Front-loaded with the core purpose and tightly packed with no filler; the token budget is stated last where it belongs. The telegraphic fragment style (parenthetical lists, semicolon-separated clauses) is dense but readable.

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

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

For a read-only analysis tool with no output schema and no annotation richness, the description covers what is returned, how results are ranked, and the size ceiling. It stops short of defining 'tier' or the exact result shape, but an agent has enough to invoke 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 carry the load, and it does explain base/head semantics (merge-base comparison like a PR; head is a ref defaulting to the working tree). The 'limit' parameter is left unexplained, so compensation is strong but not complete.

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

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

States a specific verb-ish action (analyze what a change touches) and enumerates the resource precisely: symbols changed between base and head, callers outside the diff, dangling uses, importers. It is clearly distinguishable from hotspots or repo_summary, though it never names a sibling to route against (e.g., find_references overlaps with 'callers').

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

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

Usage is implied rather than stated: 'Compares the merge base, like a PR' tells the agent the intent is diff review, and 'head: a ref, default the working tree' clarifies the default. There is no explicit when-to-use/when-not or alternative routing to siblings like find_references or file_outline.

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 only readOnlyHint provided, the description usefully adds behavior beyond the annotation: the truncation priority order (types, then methods, then fields) and a hard size cap of ~1500 tokens. That tells an agent how output degrades under load, which the annotations do not.

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 plus a size fragment, with the core purpose front-loaded and no filler. Every clause carries 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?

There is no output schema, so the description properly carries the return-value burden by describing symbols with line ranges and signatures and the truncation fallback. It is nearly complete, with the only real gap being the semantics of the 'limit' parameter.

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

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

Schema coverage is 0% and neither parameter is explained. 'path' is self-evident, but 'limit' (default 10) is never defined — it is unclear whether it caps symbol count, lines, or something else; the '<= 1500 tokens' note concerns output size, not the limit parameter's meaning.

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

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

States a specific verb+resource: it returns the symbols a file defines, with line ranges and signatures, and adds the key differentiator 'without reading it.' It is clear enough to distinguish from get_symbol or search_symbols, though it 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 only implied — the phrase 'without reading it' hints at a cheap overview step before reading a full file, but there is no explicit when-to-use or when-not-to-use guidance and no reference to alternative tools like search_symbols or repo_summary.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial context beyond that: the grouping/output shape, the exact/likely/possible confidence tiers with definitions, the ranking order (exact>likely>possible, non-test first), and a token cap of <=2000. It doesn't disclose pagination or what the limit parameter does, so it stops short of 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?

Front-loaded with the core purpose, then dense supporting clauses on output shape, tier semantics, ranking, and budget. No filler sentences; every clause adds 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?

With no output schema, the description usefully explains the return structure and ranking, which covers the output side well. But it omits input semantics (symbol format, limit behavior), leaving a gap for a search-style 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 carry parameter meaning, but it only implies the required 'symbol' argument. The 'limit' parameter (default 10) is never explained, and the expected symbol format (plain name vs qualified) is left ambiguous.

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: the call sites of a symbol, grouped by file with calling symbol and source line. This is clearly distinct from siblings like search_symbols or get_symbol, though it never names those alternatives 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 purpose (use it to find where a symbol is referenced), but there is no explicit when-to-use guidance, no mention of when to prefer search_symbols/get_symbol, and no prerequisites or input-format notes.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest of the burden and does add real context: the output shape depends on symbol kind and the response is capped at ~2000 tokens. It omits what happens on an unresolved symbol or how max_lines interacts with the cap, but the disclosed constraints are the useful ones.

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?

Extremely dense and front-loaded: the return behavior, input format, and token cap all land in three short fragments with zero filler. It is telegraphic rather than polished, but every clause carries 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?

With no output schema, the description responsibly sketches what comes back and notes the token budget. However, max_lines goes unexplained and ambiguity handling (unresolved or duplicate symbol) is absent, so it is only adequate for a lookup tool with hidden parameters.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for 'symbol' by giving accepted forms ('Order.add', qualified name, path:line), but says nothing about the second parameter, max_lines, leaving half the 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 (retrieves source) and resource (one symbol) and even describes the return shape varying by symbol kind (body for methods, member list for types). It is distinguishable from search_symbols, though it never names that 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?

There is no when-to-use guidance and no comparison against the obvious alternative, search_symbols. The accepted symbol formats ('Order.add', qualified name, path:line) describe input syntax rather than when this tool should be chosen over its siblings.

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

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

Annotations only declare readOnlyHint=true, so the description carries extra weight and delivers: it discloses the ranking formula, that renames are followed, that test files are excluded by default, and that output is capped at <=1200 tokens. That is real behavioral context an agent could not infer from the annotation.

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?

Roughly forty words, front-loaded with the core definition so the reader learns what a hotspot is first. The telegraphic fragments ('renames followed', '<= 1200 tokens') are terse but each clause carries information; nothing is 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 read-only tool with no output schema, the description covers the metric, defaults, exclusions, and token budget, but leaves the return shape vague — 'per file' does not tell the agent what fields to expect or how the score is presented, and 'limit' is never tied to the output.

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 'since' (a ref or a date such as '6 months ago', defaulting to 1 year) and 'include_tests' (test files omitted unless set), but says nothing about what 'limit' controls, leaving one of three 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?

The description names the resource (files) and the specific behavior it surfaces — files that change often and hold much code — plus the ranking metric (commits x lines inside methods). It is concrete enough for an agent to know what comes back, though it never names or distinguishes itself from siblings like diff_impact or repo_summary.

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 reach for this tool versus the alternatives in the sibling list. The only usage-adjacent text is the default window and the test-file exclusion, which are behavior, not selection guidance.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds behavior: test files are omitted by default (include_tests flips it) and output is capped at <=1200 tokens. These are non-obvious traits beyond the annotation. It omits any note on pagination/limit interaction or failure modes, so not 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?

Very compressed telegraphic phrasing that is front-loaded with the main purpose, then modes, then caveats. Every fragment carries information, though the sentence fragments ('No module: overview') cost a little 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?

With no output schema and no annotations beyond readOnly, the description partially compensates by listing what per-module results include (imports, importers, external deps, cycles). However it never explains the limit parameter's role or the overview's return shape, leaving gaps for an agent that must call it blind.

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

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

Schema description coverage is 0%, so the description must compensate. It does define the 'module' parameter's accepted forms (a name, 'pkg.*', or a prefix) and the effect of include_tests, but the 'limit' parameter (default 10, integer) is never explained in the description or schema. Partial compensation only.

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 concrete verb/resource pair: the import graph between packages/modules plus import cycles. It clearly separates the two operating modes ('No module: overview' vs 'module: ... its imports, importers, external deps, cycles'), so an agent understands the tool's scope. It doesn't explicitly contrast itself against siblings like repo_summary or find_references, which keeps it at 4 rather than 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?

Gives explicit conditional usage: omit 'module' for a whole-repo overview, pass a name/'pkg.*'/prefix for per-module detail, and note test files are excluded unless include_tests. That is clear routing within the tool's own modes. No named alternative sibling or exclusion condition is provided, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one useful behavioral constraint, the ~600 token output budget, which helps an agent plan context usage, but says nothing about pagination, caching, or what "index freshness" means operationally.

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?

Extremely tight, front-loaded, and every clause carries information: the content list, the priority signal, and the token budget. Not wasteful, though the telegraphic style borders on under-specification.

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

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

With no output schema, the description correctly summarizes what is returned and bounds the response size. For a single-optional-parameter read tool with readOnlyHint annotation, this is close to sufficient; only the limit parameter and freshness semantics remain 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?

There is one optional integer parameter (limit, default 10) with 0% schema description coverage, and the description never mentions it. The parameter is nearly self-explanatory by name and has a default, so the gap is minor, but the description does not compensate for the missing schema 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 names the resource (repo) and enumerates the specific content returned: languages, size, packages by lines, index freshness. This differentiates it from symbol-level siblings like get_symbol and search_symbols, though the verb is implicit (it returns an overview rather than performing an action).

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 a genuine usage signal, orienting the agent to call this before drilling into siblings. However, it offers no explicit when-not guidance and does not name any alternative for follow-up questions, leaving routing 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 only readOnlyHint provided, the description carries most of the burden and does so: return shape (file:line, kind, signature, no bodies), ranking rules (exact name then word match, non-test first), and a hard output cap ('<= 1500 tokens'). These are behaviors an agent cannot get from the annotation or the bare schema.

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

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

Front-loaded with the core action and packed with dense, useful detail in a handful of sentences. The inline kind enumeration is long but functional; nothing is padded, though the terse shorthand costs some 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?

No output schema and no param descriptions exist, yet the description covers return format, ranking, scoping, the empty-query mode, and truncation. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 0%, so the description must compensate and does: it enumerates valid kind values, defines path semantics including the empty-query listing mode ('types first'), and illustrates query matching. Only limit is left to its schema default, which is minor.

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 ('Find symbols by name') and immediately disambiguates from the get_symbol sibling by showing query forms ('save', 'Order.add', 'get user'). An agent can tell it is a ranked search over an index rather than a by-id fetch.

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

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

Gives concrete usage context: query syntax with word-matching, path scoping ('only in this dir, file or package'), and the special query '' behavior. It never names when to prefer get_symbol or find_references instead, so routing to alternatives is left to inference.

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