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 declares the operation read-only, requires an existing index, and clarifies whole-codebase behavior when path is omitted. It stops short of describing failure modes if the index is missing or stale, but this is adequate for a read-only 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?

Three dense sentences, front-loaded with the primary use case, then metrics, safety, prerequisite, and path guidance. No filler or redundant restatement of the tool name.

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

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

The description covers purpose, what the tool computes, read-only behavior, the index prerequisite, and the one parameter's semantics, including default behavior. An output schema is present, so not describing return values is acceptable.

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

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

The schema already documents path as an optional filter, and the description adds real value: omitting path means analyzing the whole indexed codebase, while providing it keeps results focused and fast on large codebases. That goes beyond simply restating 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 names a specific resource (the indexed codebase) and enumerates concrete analyses: cyclomatic/cognitive complexity, dependency analysis, code smells, and a quality score. This is clearly distinct from siblings like status, search, or explain, which serve different purposes.

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

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

It states when to use the tool ('code review or quality assessment') and explicitly positions it as preferred over manually reading files. It also gives the prerequisite to use the index and explains how the optional path keeps analysis focused and fast, though it does not explicitly exclude sibling tools like explain or 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 behavioral disclosure burden. It communicates that this is a single aggregated call combining multiple data sources and that it can replace Read, which is meaningful behavioral context. It does not explicitly state read-only, but the nature of 'onboarding' and 'explain' makes mutation highly unlikely.

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, no filler. The core use case is front-loaded, and the verbosity guidance is a practical addition that 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?

The description is nearly complete for a two-parameter read-style tool with an output schema. It covers purpose, use case, an alternative tool, and parameter usage. The only notable gap is a lack of explicit routing against search/find_symbol in the provided sibling list.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining when to use verbosity='summary' versus 'full', which goes beyond the schema's simple 'Output detail level' text. It does not add much for symbol_name, but the schema already sufficiently defines it.

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 ('explain'), a specific resource ('an unfamiliar symbol'), and the concrete components of the result: call-graph relationships, related code via semantic search, and quality metrics. This clearly distinguishes it from sibling tools like search or find_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?

It explicitly says to use it for onboarding to an unfamiliar symbol and points out that Read is often unnecessary, giving clear context. However, it does not explicitly state when a sibling tool like search or find_symbol should be preferred 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?

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that the tool returns the definition plus call-graph relationships, which is valuable. However, it does not state whether the operation is read-only, whether authentication or indexing is required, or any side-effect profile. The returned data is partly covered by the output schema, but safety and prerequisites are left implicit.

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

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

The description is two sentences with no filler. The first sentence states purpose and advantage, the second gives parameter guidance. Every word earns its place, and the most important information is front-loaded.

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

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

For a simple two-parameter lookup tool with an output schema present, the description covers the primary use case, the key decision about fuzzy matching, and the differentiating value over Grep. It doesn't explain prerequisites like whether an index exists, but given the tool's simplicity and the schema's completeness, this is a minor gap rather than a fail.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a decision rule for the exact parameter: 'Set exact=False for fuzzy substring matching when unsure of the exact name.' This goes beyond the schema's mechanical descriptions to tell the agent when to change the default, adding real usage 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 opens with a specific verb+resource: 'look up a specific function/class/symbol by name'. It also differentiates from Grep by adding 'preferred over Grep since it returns the definition plus its call-graph relationships in one call', giving an agent a clear reason to choose this tool over an alternative.

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

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

The description names Grep as the alternative and states the condition that makes this tool preferable. It also advises when to flip exact to false ('when unsure of the exact name'). It doesn't explicitly address other siblings like search or conditions when this tool should not be used, which keeps it from a 5, but the guidance is concrete and useful.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the transitive blast-radius behavior and the critical refactoring caveat. It does not mention output format or potential cost, but the presence of an output schema and the concise warning make it adequately transparent.

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

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

Three focused sentences, each earning its place. The core behavior is stated first, then the critical warning about transitive mode, with no filler or repetition.

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

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

The description covers the key decision drivers: what the tool does, how direction works, and when transitive mode is mandatory. Required parameters and defaults are already in the schema, and an output schema exists, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by framing transitive=True as necessary for change-impact analysis and explaining the conceptual blast radius. This extra context helps an agent choose parameter values correctly.

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

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

The description names a specific action — tracing a function's callers or callees — and clearly distinguishes the tool from generic search or symbol lookup siblings. The direction parameter is explained inline, making the tool's purpose unmistakable.

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

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

It explicitly says when to use the tool, when to set transitive=True, and contrasts it with grep, which cannot reveal transitive impact. This gives an agent actionable decision rules for using it before refactoring.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly defines the scope of behavior (liveness/readiness only) and what it does not cover. It does not describe side effects, but a health probe is implicitly read-only and the output schema is present.

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

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

The description is a single efficient sentence that front-loads the primary purpose and uses a dash to add the exclusion and sibling reference. Every word 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 zero-parameter liveness tool, the description provides complete selection guidance. The output schema covers return details, and the sibling list plus explicit status reference makes context 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?

The tool has zero parameters, so there is nothing for the description to explain. The schema already documents this with an empty object and additionalProperties: false, matching the baseline for parameter-free tools.

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 purpose: liveness/readiness probes covering uptime and engine availability. It explicitly distinguishes itself from status, so an agent can tell them apart immediately.

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 a clear when-to-use rule and an explicit exclusion: not for index freshness or completeness, with the alternative tool 'status' named. This leaves no ambiguity about 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals incremental behavior, low-memory sequential processing, live progress reporting, and automatic file watching, all beyond what the schema provides. No behavioral aspect is hidden or contradicted.

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?

Every sentence earns its place: prerequisite guidance, multi-folder syntax, memory rationale, incremental/progress behavior, and the watcher note. The critical 'Use first' instruction is front-loaded, and the text is dense without being bloated.

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

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

The description is complete for a setup/indexing tool: it explains prerequisites, invocation timing, performance characteristics, statefulness, and automatic maintenance. Since an output schema exists, return values need not be described in prose, and the context signals show a simple 2-parameter interface.

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

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

Schema description coverage is 100%, so the baseline applies. The description reinforces that comma-separated paths are supported and adds the sequential-processing context, but it does not significantly expand on the schema's already-clear parameter descriptions. It earns a baseline 3 for not degrading clarity.

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 purpose: build/refresh an index for a codebase, and explicitly frames it as the first step before almost all other tools. It distinguishes itself from siblings by noting that everything except 'status'/'health' requires an index, making its role unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use first on any new or changed codebase, before any other tool.' It also clarifies when not to run it manually by mentioning that a file watcher automatically keeps the index fresh, and identifies the two tools ('status'/'health') that do not require indexing.

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

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

With no annotations, the description must carry the behavioral transparency burden. It conveys efficiency ('quick', 'both in one call') and scope ('project understanding'), but it does not explicitly state that the tool is read-only, whether it has side effects, or what permissions or costs might apply. The non-destructive nature is strongly implied but not stated.

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, information-dense sentences with the preference statement front-loaded. Every sentence earns its place, and no content is unnecessarily repeated.

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

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

For a tool with one optional parameter and an output schema, invocation details are complete and the mode rules are actionable. The main gap is the lack of guidance for choosing between map and overlapping siblings such as graph or analyze, but the 'project understanding' framing covers most relevant use cases.

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 single detail parameter is already fully described in the schema, so the baseline is 3. The description adds task-oriented meaning by mapping each value to a use case ('quick project orientation', 'design/dependency structure') and by noting the efficiency of full in one call, which goes slightly beyond the schema's field listing.

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 map as the tool for project understanding, with summary, architecture, and full modes. It does not state an explicit verb+resource like 'Generate a project map', and it does not distinguish itself from siblings such as graph or analyze, but it is far from vague or tautological.

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

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

The description explicitly says map is PREFERRED over Glob/ls/manual browsing for project understanding and gives precise mode-selection rules: summary for quick orientation, architecture for design/dependency structure, full for both. This is clear when-to-use guidance with named alternatives.

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 discloses cross-session persistence, semantic-similarity search, and destructive cleanup behavior. It could mention irreversible deletion or TTL expiry more explicitly, but the core behavioral traits are visible.

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

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

Two sentences with no filler. The primary purpose is front-loaded, and the action mappings are compact and scannable. Every clause earns its place.

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

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

For a tool with nine parameters and no annotations, the description covers the essential decision points: which action to select and what each action accomplishes. The output schema exists and the parameter schema covers the remaining details, so the description is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description adds conceptual grouping around actions but does not provide additional parameter-level detail beyond what the schema states, which is exactly the baseline-3 scenario.

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

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

The description opens with a clear verb-resource pair: 'Persist and retrieve project context across sessions.' It then enumerates three concrete actions (store, search, delete), each tied to a specific purpose, so an agent can distinguish this memory tool from generic siblings like search and status.

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 tells the agent exactly when to use each action: save a decision/note, find memories by semantic similarity, or clean up by ID/tags/type. It lacks explicit exclusions or comparisons to sibling tools, so it is clear but does not fully meet the 'when-not and alternatives' bar.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers meaningful context: automatic fallback to live grep, stale-index warning semantics, background reindex triggering, and results still returning. It does not cover read-only/safety explicitly, but for a search tool this is substantial disclosure.

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

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

Three dense, purposeful sentences with no filler. The primary use case and preference guidance are front-loaded, followed by behavior and warning semantics — every sentence earns its place.

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

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

The description covers when to use the tool, fallback behavior, and warning semantics, and an output schema exists to document return values. It is slightly short on how mode/rerank/grep parameters interact with the described fallback, but overall an agent has enough context 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 the schema already documents all seven parameters. The description adds contextual value by mentioning 'hybrid results', 'code_snippet', and 'warning', but it does not explain parameter meanings beyond the schema, so the 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 use case ('where is/how does/find code question') and names the preferred alternative (Grep/Glob), making the tool's purpose and differentiation clear. It also signals that results are often self-sufficient via 'code_snippet', so an agent knows what this tool is for and what it returns.

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 tells the agent when to use this tool versus Grep/Glob and notes the automatic live-grep fallback. It does not explicitly contrast with sibling tools like find_symbol or graph, but the stated query-type guidance is strong enough to route most calls correctly.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains what the tool reports and discloses that a background reindex is auto-triggered when files change, which is a meaningful side-effect an agent should know about.

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 starts with the key usage guidance and then enumerates the reported fields. Every clause earns its place; 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?

The tool has no parameters and an output schema, so the description need not explain return values in depth. It covers purpose, usage timing, reported metrics, staleness behavior, and the auto-reindex side effect, making it complete for an agent to decide when and why to call 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?

The tool has zero parameters, so parameter semantics are not applicable. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than parameter details.

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 action ('Reports') and a precise resource scope: codebase index status, including index size, engine availability, memory usage, and staleness information. It clearly distinguishes itself from sibling tools like search and index by centering on index health and staleness.

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

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

The description gives explicit when-to-use guidance: at the start of a session or when search results might be stale. It does not name alternative tools explicitly, but the use cases are clear enough to guide an agent away from search or index tools.

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