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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that, the description adds substantive behavioral detail: non-indexed calls such as standard library or dependency calls are omitted, results are capped at 200 rows, and truncation is signaled via a truncated flag.

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

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

The description is front-loaded with the core purpose and then covers scope, exclusions, limits, and next step in a compact sequence. Every sentence carries useful information, with no redundant restatement of the schema or annotations.

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 is present, the description need not specify return fields exhaustively, but it still summarizes the useful return shape (call line and callee location) and covers key constraints such as indexing scope and the 200-row truncation limit. This is complete enough for an agent 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 description coverage is 100%, so both parameters already have documented semantics, including bare vs qualified name matching and repo filtering. The description reinforces that results are for definitions matching name, but adds little parameter-level detail beyond the schema.

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

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

The description opens with a specific question that defines the operation, then states it lists indexed symbols called from each matching definition, including call line and callee definition location. It explicitly distinguishes itself from find_callers, so an agent can select the right directional traversal tool without opening schemas.

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

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

It gives explicit usage guidance: use this to follow what a function does one level down, and use find_callers for who calls it. It also states the next step (get_symbol on a callee) and notes that calls into non-indexed code are excluded, leaving little ambiguity about when and how to use 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?

Annotations only declare readOnlyHint=true; the description adds substantial context beyond that: results come from the parse tree so comments/docstrings/strings never match, module-level calls are reported as kind 'file' with name '(module)', and results are capped at 200 rows with a 'truncated' flag. These are exactly the behavioral facts an agent needs before trusting or paging results.

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 question and the core behavior, then grouped into return fields, usage, sibling routing, a correctness caveat, limits, and next step. Every sentence carries distinct information with no 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?

Output schema exists, yet the description still signals the row shape and truncation semantics; combined with explicit sibling routing and next-step guidance, an agent has everything needed to call it correctly and interpret the response.

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

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

Schema description coverage is 100%, so both parameters (bare vs qualified name matching, repo scoping) are already fully documented in the schema. The description says only 'definitions matching name' and adds no matching syntax or repo semantics of its own, which is the expected baseline when the schema carries the load.

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

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

Opens with a concrete question and a specific verb+resource ('Lists every call to the definitions matching name'), then enumerates exactly what each row contains. It explicitly names what it is not (impact_of, find_callees), so the agent can distinguish it from siblings without opening a 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?

States both when to use it ('before changing a function's signature or behavior, to see its direct call sites') and the two alternatives with the condition that selects each: impact_of for transitive reach, find_callees for outgoing calls. There is also a stated next step (get_symbol on a caller).

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?

Beyond readOnlyHint=true, the description discloses concrete behavioral traits: return shape (qualified name, kind, repo, path, line range, source), the 5-match cap, the 400-line source cutoff marked 'cut', the 'total'/'truncated' pagination signals, and the caveat that unparsed files cannot be found. This is unusually complete for a read 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?

Usage guidance is front-loaded ahead of return-format and edge-case details, and each sentence carries distinct information. It is denser and longer than ideal, but no sentence 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 two-parameter read tool with an output schema and readOnly annotation, nothing an agent needs is missing: selection criteria, match cap, truncation behavior, and the unparsed-file limitation are all covered.

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

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

Schema coverage is 100%, so the parameters are already documented, but the description adds the useful cross-parameter behavior: a bare name fans out to every same-named definition each labeled with its qualified name, while a qualified name or repo narrows the result. That is genuine semantic value beyond the field descriptions, though it partially repeats the schema text.

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

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

The first sentence gives a specific verb and resource ('Read the full source of a named definition') and enumerates the definition kinds in scope. It explicitly contrasts itself with search_code and with opening files, so an agent can distinguish it from siblings without inspecting schemas.

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

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

It states exactly when to prefer this tool ('when the name is known, for example from a search_code hit') and names the two alternatives it replaces. It also gives the one exclusion case: unparsed line-window files, which should be handled with search_code instead.

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?

Beyond readOnlyHint=true, it discloses result ordering (shortest distance first), deduplication (once each at its shortest distance), a hard cap of 200 rows, and that truncated=true signals more exist. These are exactly the behaviors an agent needs to interpret output and avoid mistaking truncation for completeness.

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 motivating question and the core behavior, then routes to alternatives and next steps. The middle sentence is a dense clause stack ('once each at its shortest distance... path and line range') that takes effort to parse, 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 explained, yet the description still adds the ordering and truncation semantics that matter for interpreting results. Combined with the depth parameter rationale and sibling routing, an agent has everything needed to call and read 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 100%, so name, repo and depth are already fully documented in the schema. The description restates the depth-hop semantics and nearest-first ordering, which adds a little framing but no format or edge-case detail beyond the schema. Baseline 3 applies.

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

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

Opens with a concrete question and then states a precise verb and resource: lists every symbol that reaches the definitions matching name via call chains, nearest first. It explicitly contrasts with find_callers, so an agent can distinguish it from the closest sibling without inspecting schemas.

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

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

Gives the exact use case ('gauge the reach of a change') and names the alternative plus the condition that selects it ('for just the direct call sites and their lines, use find_callers'). It also prescribes a follow-up step (get_symbol on nearest symbols), leaving nothing 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the useful edge case that a repo with 0 files is registered but not yet indexed, which explains otherwise-confusing results. It also implies the return payload (paths, counts), though it doesn't say anything about ordering or size 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?

Three short sentences, front-loaded with the purpose and ending on the indexing caveat. The opening rhetorical question is a small stylistic flourish rather than wasted content, but the whole thing earns its length.

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 doesn't owe return-value details, yet it still summarizes the payload and handles the empty-repo ambiguity. For a no-argument, read-only listing tool this covers everything 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?

Zero parameters, so the baseline of 4 applies and there is nothing the description needs to compensate for. The schema coverage being 100% on an empty object means no additional parameter explanation is required or expected.

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 (registered repositories) and states exactly what is returned: paths plus file and symbol counts. It is clearly a discovery/enumeration tool, distinct from the query-oriented siblings like search_code, get_symbol, or impact_of.

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

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

It gives two explicit triggers: use it to learn valid repo values for the other tools, or after a repo was refused. That is both a positive condition and an error-recovery condition, leaving little to infer about when to reach for this instead of a sibling.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the actual effect: a small, capped boost in later searches that fades over 30 days. That is exactly the consequence an agent needs to judge whether calling is worthwhile, and it confirms nothing destructive happens.

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

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

Four tight sentences, front-loaded with the purpose and the invocation condition, followed by the payoff and the exclusion. Every sentence contributes a distinct piece of guidance with no padding.

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

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

With an output schema present and full schema coverage, the description only needs to cover intent, timing, provenance of inputs, and side effects — all of which it does. Nothing required to call the tool correctly is missing.

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

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

Schema coverage is 100%, so each of repo/path/name is already documented with examples. The description reinforces the key constraint ('pass them exactly as search_code returned them') but adds no format or edge-case detail the schema doesn't already carry, so the baseline 3 applies.

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

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

The description opens with a precise verb+resource framing ('Tell the server a result helped') and scopes it to search hits that are cited or relied upon. It also distinguishes itself from adjacent tools by noting that get_symbol and read_wiki already register a lighter use, so an agent can tell what this tool uniquely does.

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

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

It gives an explicit trigger ('call this for each search hit you cite in your answer or rely on') and an explicit exclusion ('mark only what you actually used', since reading via get_symbol/read_wiki already counts). Both the when and the when-not are stated rather than inferred.

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 most of the burden and delivers real operational context: pages can be fresh or stale, what made them stale, and that a stale page describes code that has changed and its citations should be checked. It also discloses the citation payload shape (repository, path, line range). Some of the return detail overlaps the existing output schema rather than adding new behavioral information, which keeps it just below the top score.

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

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

Purpose is front-loaded, then read-mode behavior, then list-mode behavior, then next step — a logical order with each sentence doing work. It is longer than necessary for a two-parameter tool, and the return-value paragraph partly duplicates the output schema, but nothing is filler.

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

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

For a read-only lookup tool with full schema coverage, annotations and an output schema, the description supplies everything an agent needs to choose it, pick a mode, and interpret staleness. The one remaining gap — pagination or size limits on listings — is minor and not implied by the 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?

Schema coverage is 100%, so baseline is 3; the description goes beyond the schema by framing the two modes (pass page to read one page, omit it to list) and by stating that listing can be scoped to one repo with name, state and first purpose line. It adds no syntax or format nuance beyond what the parameter descriptions already say, so it sits modestly above baseline.

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

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

States a specific verb and resource ("Reads the tool's wiki page about a module") and immediately glosses the resource ("a directory of indexed code") so the domain concept is unambiguous. It also distinguishes the tool from its nearest sibling: use it for a module as a whole "rather than one function" (get_symbol), which lets an agent route correctly 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?

Gives an explicit trigger (question about a module as a whole, or after search_code returns a hit of kind page), an explicit alternative (get_symbol for a single symbol), and a prescribed next step (get_symbol on a key symbol). The omit-page-versus-pass-page branch is stated in prose, so both invocation modes are covered.

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?

Beyond the readOnlyHint annotation, it discloses the ordering of results (fresh first, most confident or topic-relevant first), the exact fields per fact, what 'stale' means and why it matters, the distillation source, and when distillation occurs. This is rich behavioral context an agent cannot get 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?

Front-loaded with purpose and timing, then return shape, then next steps. It is long and dense, but nearly every sentence carries functional detail (staleness semantics, provenance, next step) rather than padding.

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

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

With an output schema present, the description still covers return semantics, staleness handling, and follow-up actions, plus the readOnlyHint annotation covers safety. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description only echoes the topic-ordering behavior and repo scoping that the schema states, adding little beyond it. Baseline 3 is appropriate.

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

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

States a specific verb and resource: loads facts earlier sessions derived about a codebase. It clearly distinguishes itself from siblings by framing recall as the pre-search memory step versus search_code and get_symbol.

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

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

Explicitly says when to call it ('at the start of a session, and before searching') and routes the agent elsewhere for gaps ('get_symbol ... or search_code for what recall does not cover'). Alternatives and conditions are named.

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 declare readOnlyHint=true, and the description is consistent with a read-only search. Beyond that, it discloses ranking mechanics, feedback fading over 30 days, fused keyword/semantic search, special hit kinds (page and fact), and state semantics for wiki pages.

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

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

The description is front-loaded with purpose and usage, then details results and next steps. It is somewhat long and repeats the feedback/relevance relationship and default limit that the schema already covers, so it is not maximally 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?

For a complex search tool with an output schema, the description supplies the semantic context an agent needs: ranking fields, feedback behavior, page/fact hit meanings, stale/fresh state, and next steps. Nothing essential for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds useful meaning for feedback behavior (max 20 percent boost, fading over 30 days, relevance as pre-feedback score) and limit/return behavior, though it does not add much for repo or language beyond the schema.

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

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

States a specific verb and resource: 'Find code by what it does or by name,' with concrete query examples. It explicitly distinguishes itself from siblings by saying to use it first when the symbol is unknown, and routing known-name lookups to get_symbol, find_callers, or impact_of.

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

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

Gives explicit when-to-use guidance: use this first when you do not yet know which symbol to look at. It also names the alternatives for known symbols, call sites, and impact analysis, plus concrete next steps after a hit.

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