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 disclose the analytical mechanism and the kinds of results produced (direct dependents, transitive impact, tests, risk assessment). However, it doesn't state that the operation is read-only/non-mutating, nor does it note limitations of static import-graph analysis (e.g., dynamic imports or runtime-only dependencies), which matter for trusting the prediction.

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 behavior in the first sentence, followed by a compact mechanism summary. The Returns section is somewhat redundant given an output schema exists, but overall it is tight 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?

For a single-parameter analysis tool with an output schema (which covers return values), the description supplies enough: purpose, mechanism, and the path constraint. The main remaining gap is sibling routing and analysis limitations, but the essentials are present.

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 parameter has 0% schema description coverage, so the description must compensate, and it does: 'path: File path relative to project root' adds the critical relative-to-root constraint absent from the schema. This meaningfully closes the gap for the one required param.

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+resource: it predicts breakage from a file change, and it names the mechanism (import graph, direct dependents, transitive impact, related tests). It is clearly distinguishable in substance from siblings like get_file_relations or find_dependency_path, though it doesn't name them 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 by the purpose ('if you change a file'), with no explicit when-to-use or when-not-to-use guidance. Related siblings such as get_file_relations and search_with_dependencies are not referenced as alternatives, 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?

No annotations are provided, so the description carries the full burden. It discloses the per-mode file caps, which is a genuine behavioral limit, but says nothing about whether the scan is read-only, cost/latency implications of 'deep', or how the analysis behaves on very large repositories.

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 purpose and followed immediately by the mode distinction. Nothing is wasted, though the terseness borders on under-specification rather than crisp brevity.

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. However, with no annotations, 0% schema coverage on a 2-param tool, and an unmentioned target_path, the definition leaves an agent guessing about the second parameter and about cost/safety behavior.

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 does explain 'mode' meaningfully (quick=100 files, deep=1000), well beyond the bare string schema. But 'target_path' is never mentioned, and what the file numbers mean (files scanned vs sampled) 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 and analysis target ('Analyze cyclomatic complexity'), so the resource is unambiguous. It does not differentiate itself from close siblings such as analyze_code_quality or analyze_project_structure, which keeps it below 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 two modes imply a usage choice (quick for breadth 100 files, deep for up to 1000), which is useful guidance. However, there is no statement of when to prefer this tool over analyze_code_quality or when not to use it, and no prerequisites are given.

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 one useful limit ('mode=deep raises max_files cap to 100'), which implies a default cap of 10, but says nothing about runtime cost, whether the scan is read-only, what happens when target_path is invalid, or how results are aggregated.

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 zero filler and the core mechanism front-loaded. It is efficient, though the terseness tips into under-specification rather than optimal sizing.

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. However, with no annotations and 0% parameter coverage, the description leaves too much open for a tool with a mode switch and a path argument: it omits target_path entirely and never characterizes what a 'quality scan' produces or costs.

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 all three parameters. It explains only the mode/max_files interaction; target_path is never mentioned, and the difference between 'quick' and 'deep' beyond the file cap is left 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?

States a specific mechanism and resource: 'Pylint-based quality scan'. That is enough to tell it apart from analyze_code_complexity or search_for_errors by inference, but the description never explicitly scopes what 'quality' covers (lint errors, style, warnings) nor names the sibling it is not.

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 exclusions. The only selection hint is the inline note about mode='deep', which is about parameter choice rather than about when this tool is the right one versus analyze_code_complexity or search_for_errors.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 behavioral burden. It discloses that the tool analyzes dependencies and requires no indexing, and it briefly describes the return shape. It does not explicitly confirm read-only behavior, side effects, permissions, or how project context is selected.

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 and compact: it states the analysis target, supported manifests, lack of indexing requirement, and return content. Every sentence contributes useful selection context without 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?

Because an output schema exists and there are no parameters, the description does not need to explain return fields in detail. It covers supported languages and manifest files and notes that indexing is unnecessary. The main remaining gap is that it does not clarify which project/root context the analysis applies to.

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 are no parameter semantics to explain. The baseline for a zero-parameter schema is 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 specific verb and resource: it analyzes project dependencies, including versions, pinning strategy, duplicates, and lock files. It also scopes supported ecosystems and notes that no indexing is required. It does not explicitly distinguish itself from sibling dependency tools such as get_dependencies_with_depth or find_dependency_path.

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 listed analysis targets (versions, pinning, duplicates, lock files) and the supported manifest types. The description does not say when to choose this over sibling tools like get_dependencies_with_depth, nor does it state exclusions or prerequisites.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 indexing is not required and that a formatted report is returned, but it omits whether the operation reads files, whether it has side effects, permission requirements, and performance characteristics.

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

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

The description is short and front-loaded: it states the detection scope first, then the no-indexing requirement, then the return and memory-saving behavior. Every sentence adds useful information without repetition or 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?

Given zero parameters and an existing output schema, the description does not need to explain return values. It adequately covers detection scope and the no-indexing constraint, though it could be more complete by clarifying its relationship to related convention and tech-stack tools.

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 the schema is an empty object, so there are no parameter semantics to clarify. The baseline score for no parameters 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 uses a specific verb ('auto-detects') and resource ('project conventions') and enumerates the convention categories detected. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as extract_tech_stack or analyze_project_structure.

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 stating it 'Does NOT require indexing' and that results can be saved to memory, which gives some context. However, it never states when to use this tool versus alternatives like extract_tech_stack, get_project_overview, or save_conventions_to_memory.

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 'very fast, no indexing needed' and the tree-shaped return, but says nothing about behavior on missing/invalid paths, hidden-file handling, truncation when max_items is hit, or permission requirements.

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 statement, then scannable Args/Returns blocks. The Returns section is mild redundancy since an output schema exists, but the rest 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 3-param, all-optional read tool with an output schema, the description covers purpose, parameters, constraints, and the key performance trait. Only edge-case behavior (missing path, truncation, hidden files) is left unaddressed.

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 fully compensates: it explains that path is relative to project root with '.' for root, bounds depth to 1-3 (a constraint absent from the schema, which has no enum or maximum), and gives max_items semantics plus its default.

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 ('Lists files and subdirectories at the given path') and adds a scope hint ('navigate the project tree level by level'). It does not name any sibling (e.g. search_codebase, get_project_overview) as the alternative, so differentiation is implied rather than explicit.

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 this to navigate the project tree level by level' gives clear usage context, and 'no indexing needed' implicitly positions it against index-dependent search siblings. No explicit when-not-to-use or named alternative is given.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 does disclose the no-path case ('message if no path found') and the depth default, which helps, but it never states that the operation is read-only, whether edge direction means dependencies-of-source or dependents, how cycles are handled, or the cost of raising max_depth on a large graph.

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 one-line purpose sentence is front-loaded, and the Args/Returns blocks are compact and skimmable. The only waste is restating the max_depth default that already appears in the schema's default field.

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 means return values needn't be spelled out, and the args are covered, but for a graph-traversal tool sitting among many dependency-related siblings the definition omits the routing guidance and traversal semantics an agent needs to call it with confidence.

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 fully compensates for the two path parameters by specifying they are relative to the project root, plus the default and intent of max_depth. It falls short of explaining what a max_depth cutoff does (truncated result vs. error) or how paths are normalized.

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: 'Finds the shortest dependency path between two files.' This is clearly distinct from set-like siblings such as get_file_relations or get_dependencies_with_depth, but the description never explicitly contrasts itself with those nearby tools, so differentiation is left 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 reach for this tool versus check_dependencies, get_dependencies_with_depth, or get_file_relations, all of which operate on the same dependency graph. The Args block implies the shape of a call but gives no selection criteria 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 must carry behavioral load; it does disclose that matching is case-insensitive, that partial names are accepted, and that it works without the vector index — genuinely useful traits. It says nothing about ranking/ordering of results, ambiguity handling, or the fact that it is a read-only lookup, which a no-annotation tool should ideally make explicit.

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 one-line purpose followed by compact Args and Returns blocks. Every line carries information; nothing repeats the name or pads 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 shape needn't be spelled out, and the description nonetheless sketches file:line plus caller/callee counts. For a two-parameter lookup tool, the only real gap is result ordering and how partial matches are ranked.

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, and it largely does: it explains that 'name' matches exactly or partially and is case-insensitive, and that 'n_results' caps results with a default of 8. That covers both parameters with meaning the bare schema does not provide.

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: finds where a function/class/method is defined, via the AST symbol graph. The 'works without the vector index' clause implicitly separates it from the embedding-based search tools (search_codebase, search_codebase_advanced), though no sibling is named outright.

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 'no embedding model needed' note implies when this is the right pick over vector search, but the connection is left for the agent to infer. There is no explicit 'use this when / prefer search_codebase when' routing, and no noted 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 at all, the description bears the full burden; it does disclose the key trait that indexing is unnecessary and that results include file locations. It does not state read-only semantics, any size/truncation behavior on large codebases, or scope limits (e.g., whether vendored/generated dirs are skipped).

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 single sentence states the behavior, followed by tight Args/Returns blocks. Every line earns its place; the only minor waste is the Returns block partially duplicating the output schema.

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 read tool with an output schema, the description covers the scan behavior, the non-indexing prerequisite, the parameter semantics, and the shape of results. Nothing an agent needs to call this 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 0% and the single parameter has no schema description, so the description must compensate — and it does, explaining that tag is an optional filter, giving concrete examples ('TODO', 'FIXME'), and defining the null case as all tags.

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 ('scans') and resource ('codebase') plus the exact set of markers searched (TODO, FIXME, HACK, BUG, XXX). This clearly separates it from generic siblings like search_codebase or query, though it never names an alternative 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?

'Does NOT require indexing' gives an important contextual cue that this can be run before/without index_codebase, which is useful selection signal. However, there is no explicit when-to-use/when-not statement and no named alternative for broader comment or text search.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 identifies the operation as a read and states the return format is Markdown, but it does not discuss permissions, missing-file behavior, or any other edge cases.

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 with the core action. The Args and Returns sections add useful structure without unnecessary 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?

For a one-parameter read tool with an output schema, the description is largely complete. It explains the parameter's two modes and the return format, though it could do more to distinguish sibling tools.

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 so by explaining that path selects a specific file and that an empty path triggers a coverage overview with all annotated files.

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: 'Reads file annotations.' It also clarifies the alternate mode when path is empty. It is clear but does not explicitly distinguish itself from siblings such as save_annotation or list_unannotated_files.

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 explains the two usage modes: a specific file path reads that file's annotation, while empty path returns a coverage overview. However, it does not state when to use this tool versus related alternatives like save_annotation or list_unannotated_files.

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 implies a read-only operation via 'Returns' but never states that there are no side effects, whether it requires permissions, or how expensive it is to call.

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-loads the core purpose. The 'Returns:' line is somewhat redundant given the output schema, but it does not bloat the description significantly.

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 statistics getter this is adequate but minimal. It explains what is returned, but with no annotations it omits behavioral context such as read-only safety and call conditions, leaving the agent to infer usage.

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 of 4 applies. The description has no parameter semantics to explain, and the schema is empty.

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 (returns) and resource (performance statistics for all caches), which is clear and distinct from stats siblings like get_index_stats that cover a different subject. It does not explicitly compare itself to any sibling, but no sibling is a direct alternative for cache statistics.

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 only states what the tool returns, with no indication of when to call it, when not to call it, or what alternatives exist. There is no guidance on prerequisites such as whether caches must be initialized.

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, and it delivers real behavioral facts: no LLM calls, deterministic output, sub-500ms latency, budget packing, and an empty string when the index is cold. What remains undisclosed is the indexing prerequisite in operational terms (must index_codebase have run first?) and any error/permission 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-loaded with the core promise, then clean Args/Returns sections with no duplicated filler. The opening 'scout pyramid, layer 0' is internal jargon that costs a clause without informing the agent, a small deduction.

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 4-parameter retrieval tool this is nearly self-sufficient: it covers what goes in, what comes out, cost profile, and the empty-index edge case. The remaining gap is workflow context — how it relates to the many search_* and get_* siblings in a 60-tool server.

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 it does: all four parameters get meaning, including the crucial note that hint_files/hint_symbols are 'client-extracted' from the task text, plus the 4000 default for budget_tokens. It could go further on acceptable hint formats or budget trade-offs, hence 4 rather than 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?

States a specific verb+resource ('Context brief for a coding task') and details the composition of that brief: hybrid retrieval, one-hop import-graph expansion, file skeletons, git recency. An agent can tell it produces a packed markdown digest rather than raw search hits. It never names a sibling to contrast with, though, 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 scout pyramid, layer 0' implies a first-step workflow position, and 'Zero LLM calls, typically <500ms' implies it is cheap enough to call eagerly. But there is no explicit when-to-use/when-not guidance and no reference to alternatives like search_codebase, search_codebase_advanced or get_project_overview, leaving the routing decision 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 provided, so the description carries the full behavioral burden. It clearly indicates a read-style retrieval operation and explains depth and direction, but it does not mention error handling, performance characteristics, or explicit read-only/safety 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?

The description is concise and well-structured with Args and Returns sections. It front-loads the core purpose and uses every line to convey relevant invocation details without unnecessary verbosity.

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 is moderately complex with three parameters and an import-graph traversal. The description covers purpose, all parameters, and return semantics, and an output schema exists so return values need not be detailed further. It lacks only explicit routing guidance versus sibling dependency tools.

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 document parameter meaning. It does so for all three parameters: file_path is relative to project root, depth is 1-5 with default 2, and direction is downstream or upstream with clear definitions.

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: getting file dependencies in the import graph up to a specified depth. It is clear what the tool does, but it does not explicitly distinguish itself from sibling dependency tools such as get_file_relations, check_dependencies, or find_dependency_path.

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 through the direction parameter, which explains downstream vs upstream traversal, and the depth range. However, the description does not explicitly say when to choose this tool over alternatives like check_dependencies or find_dependency_path.

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 that results come from static analysis and require no indexing, and it names the categories of relationships returned, but it omits permission requirements, error behavior for missing files, and any limits on graph depth.

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 front-loaded with the core purpose, then provides compact Args and Returns sections. Every sentence contributes useful information with no redundant repetition of schema or title content.

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 single-parameter read tool with an output schema, the description supplies the purpose, source method, parameter meaning, and returned information at an appropriate level of detail. The output schema covers return structure, so the description need not elaborate further.

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 add meaning for the single required parameter. It does so by specifying that path is a file path relative to the project root, which is more precise than the schema's bare 'Path' title.

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: it shows import relationships for a file, including what it imports, what imports it, and related test files. This is clearly distinct from general file summaries, but it does not explicitly distinguish itself from siblings like get_symbol_relations or analyze_change_impact.

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 no explicit guidance on when to use this tool versus alternatives such as analyze_change_impact, get_dependencies_with_depth, or get_symbol_relations. The note that it is built from static analysis and needs no indexing implies usage context, but there are no exclusions or alternatives 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?

With no annotations, the description carries the full burden and does disclose a key trait: no index needed, so it works on unindexed files. It also bounds the payload ('lightweight', first N lines). It omits error behavior for missing files and whether language support is limited, keeping it short of 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 core purpose is front-loaded in the first sentence, and the Args/Returns blocks are terse and scannable. No filler sentences.

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 only a headline, which is provided. Combined with per-parameter docs and the indexing caveat, the description is sufficient to call the tool correctly; only edge-case behavior is absent.

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 it does: path is defined as relative to project root, and max_lines is explained as content lines to include with the default 50 restated. Only missing detail is units/validation semantics for max_lines.

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 ('Returns a lightweight summary of a file') and enumerates exactly what the summary contains: size, imports, top-level definitions, and first N lines. The 'Does NOT require indexing' clause distinguishes it from indexed siblings like search_codebase, though no sibling is named 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 'lightweight' and 'does NOT require indexing' framing — an agent can infer this is a cheap peek before or instead of indexing — but there is no explicit when-to-use/when-not statement and no named alternative such as get_file_relations or search_codebase.

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 enumerates the complete status state machine, includes timing expectations for slow phases, mentions the `last_error` field on failure, and states the return format. It omits safety/read-only framing and polling-frequency guidance, which keeps it below a 5 for a no-annotation 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 front-loaded with the core purpose, then uses a compact status list that directly supports correct interpretation of the tool's output. The status list is long but every entry is informative for an agent polling progress; only minor tightening is possible.

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?

Even though an output schema exists (so return detail is not strictly required), the description adds useful state-machine context and error semantics. For a read-only progress tool with no parameters, this is complete enough that an agent can call it and interpret the result 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 takes zero parameters, so there is nothing to explain beyond the absence of arguments. The baseline for 0 params is 4, and no additional param semantics are needed.

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 ('Returns the current status of a background indexing operation') and explicitly ties it to `index_codebase()` with background=True. This distinguishes it from siblings like `index_codebase` (starts the job) and `get_index_stats` (likely reports index contents rather than live progress).

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 clearly establishes when to use it: after starting a background indexing operation, which it notes is the default behavior of `index_codebase()`. It does not name explicit exclusions or alternatives (e.g., when to use `get_index_stats` instead), but the context is strong enough for correct selection.

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

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

With no annotations, the description carries the full burden and does disclose two meaningful traits: it is fast and it does not trigger vector store initialization, which implies no expensive side effects. It stops short of stating read-only status or cost/limits explicitly, but 'Returns statistics' makes the non-mutating nature clear.

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, result stated first, the performance caveat second. No filler, no restating of the tool name, and the most decision-relevant fact (it's cheap) is front-loaded after the purpose.

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 needn't be described, and with zero parameters the input side is trivially complete. The description covers purpose and cost profile adequately; only the relationship to sibling inspection tools (index progress, cache stats) is left unaddressed.

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. The parenthetical hint at what the returned statistic is adds a small amount of direction without duplicating 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: 'Returns statistics about the current vector store (number of chunks).' An agent can tell this is a read-only inspection call, but it never distinguishes itself from nearby siblings like get_index_progress or get_cache_stats, which could plausibly return overlapping information.

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?

'This operation is very fast and doesn't trigger vector store initialization' implicitly signals a cheap, safe pre-check, but there is no explicit when-to-use statement and no named alternative (e.g., use get_index_progress while indexing is running). Usage must be 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?

With no annotations provided, the description carries the behavioral burden. It discloses the core algorithm, defaults for the optional parameters, and that results are sorted by similarity, but it does not state whether the operation is read-only, mention performance characteristics, or clarify 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-loaded, with purpose stated first and Args/Returns sections used efficiently. Every line adds useful meaning without unnecessary 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 tool is a read-style analysis operation with an output schema available, and the description gives enough information about inputs, algorithm, and result ordering for an agent to call it correctly. Some behavioral context, such as performance or relationship to similar sibling tools, is still 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%, so the description must document all parameters. It does so for all three: file_path is relative to project root, similarity_threshold is a 0.0-1.0 score with default 0.3, and max_cluster_size defaults to 20.

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: finds files closely related to a target based on shared dependencies using Jaccard similarity. This is clear enough to distinguish it from generic search, but it does not explicitly differentiate it from nearby sibling tools such as get_file_relations or get_dependencies_with_depth.

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 when to use it by explaining that it identifies modules that work together based on shared dependencies. However, it provides no explicit when-to-use guidance, exclusions, or named alternatives among the sibling dependency and relation 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?

No annotations are provided, so the description must carry the burden, and it does disclose the key non-obvious trait: "Does NOT require vector store or indexing," implying no prior setup and low cost. It does not state side-effect/read-only status explicitly, but the read semantics are evident from the return description.

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 statement, then the free-of-setup caveat, then usage ordering — all in three short lines. The "Returns:" block partially duplicates the existing output schema, a small redundancy, though it aids quick scanning.

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 zero parameters, an output schema present, and no destructive behavior possible, the description covers everything an agent needs: what it returns at a high level, that no indexing is required, and that it should be called first.

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 no parameter semantics to document and the description correctly does not invent any.

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 ("Returns ... overview of the project") and scopes it with "fast, lightweight," which separates it from heavier analysis siblings like analyze_project_structure. It does not name an explicit alternative, 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?

"Use this FIRST to understand the project before diving deeper" gives clear sequencing guidance that positions it ahead of the many explore/analyze siblings. It lacks explicit when-not conditions or named alternatives (e.g., get_context_brief, project_onboarding), so 4 rather than 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 return shape (related symbols with file:line, or full info), which is useful, but says nothing about whether the codebase must be indexed, what happens for an unknown or ambiguous symbol, or whether results are bounded.

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 one-line summary is front-loaded, followed by a compact Args/Returns block with zero filler. Every sentence adds information an agent needs.

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 annotations and an output schema already covering returns, the description covers the essentials (param format, relation values) but omits prerequisites such as index state and symbol disambiguation. For a graph-query tool this leaves meaningful 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 coverage is 0%, so the description must compensate, and it largely does: it lists every accepted relation value with the default and specifies the bare-name format for symbol ("UserService"). The one gap is that the distinction between "usages" and "callers" is not explained, which matters for picking the right value.

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: returns AST-level relations of a symbol from the symbol graph, which is clearly different from file-level or search tools. It does not explicitly contrast with close siblings like find_symbol or get_file_relations, leaving the agent to infer the boundary.

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 enumerated relation values imply the use cases (impact analysis, hierarchy exploration), but there is no explicit when-to-use or when-not-to-use guidance relative to find_symbol, get_file_relations, or analyze_change_impact. The agent must infer which tool to reach for.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 burden and does well: it discloses the read-only, lightweight nature, explicitly bounds side effects by stating it will not initialize the vector store or embeddings model, and names the concrete fields reported. It does not state the return semantics beyond format, or error behavior, so it falls just short of 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?

Front-loads the purpose in one line, then lists the reported fields and the explicit non-goal, then the return format. Every sentence earns its place; the only mild redundancy is a separate 'Returns' block for a format the output schema already implies.

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 read-only check with an output schema present, the description gives enough: what is inspected, what is excluded, and the response format. Missing only minor detail such as whether it can fail hard or what the report looks like when degraded.

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 the description could add or omit. The schema coverage is 100% and no param information is needed.

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 ('readiness check for the ProjectMind MCP server') and enumerates exactly what it inspects: version, project root, memory file status, index status, and root-validity. This is clearly distinct from siblings like maintenance_status or get_index_stats, which cover deeper/longer-running diagnostics.

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 word 'readiness check' implies a pre-flight/diagnostic use, and 'Lightweight' plus 'Does NOT initialize the vector store or embeddings model' hints at when it is preferable to a heavier init. However, no sibling alternative is named and there is no explicit when-to-use/when-not statement.

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 the key non-obvious trait: the default is non-blocking with embedding offloaded to a daemon thread, and how to poll completion. It does not cover concurrency behavior (what happens if indexing is already running), failure modes, or what state is written.

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 purpose and the default mode in the opening two sentences; the Args block earns its space. The phrase '(old behaviour)' is extraneous padding and the 'Returns' line adds little, but overall it is tight for a one-parameter tool.

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?

A one-parameter tool with an output schema, and the description covers both the operating mode and how to monitor progress via a sibling. Nothing essential is missing, though a note on whether concurrent runs are safe would round it out.

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 single parameter has a bare boolean with a default, so the description does all the work. The Args block explains exactly what True/False mean behaviorally (returns immediately vs. blocks until complete), enabling correct invocation without guessing.

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?

First sentence states a specific verb (indexes) with a precise scope (only changed files since last indexing), which distinguishes it from a full index_codebase sibling in substance. It never names that sibling explicitly, so the differentiation is implicit rather than spelled out.

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 incremental framing implies when to reach for it, and calling index_changed_files when a full reindex is needed is left to inference. It does route the agent to get_index_progress for monitoring, but there is no explicit when-not or named alternative for a full index.

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, and the description carries the full burden well: it discloses the default background daemon-thread behavior, that it returns immediately while embedding continues, that force clears the existing index, and that blocking mode may timeout on large codebases. These are exactly the traits an agent needs before invoking a long-running mutation.

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 one-line purpose and the size limit, which is the right ordering. The trailing Returns section largely restates what the background arg paragraph already established, so there is some redundancy, but nothing is unclear.

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-param tool with no annotations, the description covers scope limits, default mode, side effects, timeout risk, return shape, and the progress-polling follow-up. Despite an output schema existing, the return description adds useful mode-specific differentiation.

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 it does: both parameters are explained with their defaults and consequences, including what force destroys and what flipping background changes in return value and blocking behavior. The schema's bare booleans would be ambiguous without this.

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 ('Indexes the entire codebase') plus the purpose ('for semantic search'). The 'entire codebase' scope cleanly separates it from the sibling index_changed_files and search_codebase.

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 alternative ('For large codebases use index_changed_files() instead') tied to a concrete threshold (5000 files per operation). It also names get_index_progress() as the polling follow-up and spells out when to pick background=False vs the default.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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. It transparently explains that it returns missing and stale annotation lists plus coverage stats, and that limit applies per category, but it does not define what makes an annotation stale or whether this depends on a prior 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?

The description is front-loaded with the core purpose, followed by workflow context and then parameter and return details. The Args/Returns structure is efficient and every sentence contributes useful selection or invocation context.

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 one-parameter listing tool with an output schema, the description covers purpose, workflow, the limit parameter, and the return categories. Minor gaps remain around prerequisites and the exact stale-annotation criteria, but the core invocation context is 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 by explaining that limit is the maximum number of files per category, not just a total. The default of 20 is also stated, matching 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 uses a specific verb and resource: it lists code files lacking annotations or with stale annotations. It also explicitly connects the output to save_annotation(), making its role distinct from the action-oriented 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?

It gives a clear recommended workflow: save or refresh annotations after working on a file, and periodically run this tool to find backlog files. It does not explicitly name when-not-to-use alternatives such as get_annotations(), but the usage context 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 must carry the behavior burden. It usefully discloses that execution is synchronous and returns a per-task report, but it does not describe side effects, mutation scope, idempotency, or safety implications of running all self-healing tasks.

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 filler, and the synchronous nature is front-loaded so an agent immediately understands the blocking behavior.

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 description covers synchronous execution scope. However, for a no-annotation tool that may trigger codebase changes, the description remains thin on what the self-healing tasks do, whether the operation mutates state, and how it differs from maintenance_status.

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 per the rubric the baseline is 4. There are no parameter semantics to clarify or omit.

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 scope: 'Synchronously run every self-healing task once.' This clearly differentiates a run action from status-oriented siblings like maintenance_status, though it does not name 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?

The word 'Synchronously' implies a blocking execution useful when you want maintenance done immediately, but there is no explicit guidance on when to use this versus maintenance_status or prune_index, nor any stated preconditions 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 load. 'Reports' implies a safe read with no side effects, and it names the three data categories returned; but it does not state cost, freshness, or whether calling it affects the daemon. It stays at a minimum-viable level of behavioral 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?

A single front-loaded sentence with no filler. Every clause (status, schedule, recent history) adds concrete scope and nothing is redundant.

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 parameters and an output schema handling return-value detail, the description only needs to say what the call is for, which it does. The remaining gap is whether the reported 'recent history' has a fixed window or time range, which an agent may want to know.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly implies nothing must be supplied to obtain a full status report.

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 ('Reports') and resource (the self-healing daemon's status, schedule, and recent history). The content enumerated makes it clearly distinguishable from mutation siblings like maintenance_run and prune_index, 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: it reads as the read-only inspection counterpart to maintenance_run, but the description never says when to call it versus triggering a run. No exclusions or prerequisites are 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?

No annotations are provided, so the description must carry the full burden. It discloses that results are saved to memory, a side effect, and that it runs multiple sub-tools, but lacks details on permissions, safety, or whether it is idempotent.

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 a summary, followed by specifics and a return note. It is efficient with no redundant 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 are covered. The description adequately explains the composite nature and memory saving, but could note any prerequisites or side effects for a tool with no annotations.

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 the baseline is 4. The description appropriately does not discuss parameters, as none exist.

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 composite action: runs overview, conventions, dependencies, and TODOs, then compiles a brief for onboarding. It is clear what the tool does, though it does not explicitly differentiate from siblings like get_context_brief or generate_project_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?

The description provides clear context: 'for onboarding a new developer or AI.' It implies when to use the tool but does not explicitly exclude alternatives or state prerequisites.

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 destructive operations (drops orphan chunks) and that force deletes and rebuilds the entire collection from scratch. It stops short of stating irreversibility, expected runtime, or whether the index is unavailable during the rebuild.

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 filler; the default behavior is stated first and the escalated destructive mode second, which matches how an agent would evaluate risk.

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 behavior is covered. What is missing for a destructive maintenance tool with zero annotations is the safety envelope: irreversibility, cost/duration, and how it relates to sibling index and maintenance tools.

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% for the single `force` parameter, so the description must compensate and does: it explains that force=True deletes and rebuilds the entire collection rather than pruning in place. The default false is left implicit, but the semantic consequence of the flag is clear.

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 and resource ('prunes the vector index') and enumerates the concrete operations (drop orphan chunks, VACUUM, optional full rebuild). An agent knows exactly what the tool does, though it never contrasts itself with index_codebase or maintenance_run, which also touch the index.

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 pruning is warranted versus rebuilding via index_codebase or running maintenance_run. The only conditional offered is what force does, not when to reach for this tool or when to avoid 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 carries the full load, and it discloses the escalation policy, latency expectations for the cheapest tier, and that fallback tiers only engage on weak signal. The read-only nature is implied but never stated outright, and nothing is said about needing a built index before queries return useful 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 one-line value proposition and the sibling comparison, then structured Args. The repeated 'L0 + L1 + L2' listing for semantic and deep is slightly redundant, but nothing is wasted overall.

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. The description covers cost, tiering, and every parameter, which is what an agent needs to invoke it. It stops short of noting the prerequisite that the codebase must be indexed (a sibling tool exists for that), which is the one operational detail an agent could trip on.

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 schema has no enum on `intent`, yet the description documents all three parameters: free-form text, the four valid intent strings with their tier mappings and behavioral differences, and the 1-50 range for n_results. This is materially more information than the schema conveys.

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 (project query) and its distinguishing mechanism (tiered L0/L1/L2 retrieval), and explicitly positions it against a sibling with 'Cheaper than `search_codebase`.' It is clear what the tool does, though the generic name 'query' means the description has to carry the identity, which it does adequately.

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 cost comparison against search_codebase and maps each intent value to concrete behavior (overview = L0 only and sub-second; deep = relaxed thresholds). There is no explicit 'when not to use this / use X instead' for the other search siblings, but the alternative routing is clear enough to choose 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, the description carries the full burden, and it does disclose a key behavioral trait: output may be truncated depending on max_lines. It says nothing about prerequisites (project root initialization), the memory format, or whether the read is scoped to the current project only.

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 one-line purpose, then Args/Returns. Every sentence carries information about the parameter or return, though the docstring scaffolding adds mild overhead.

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 and the parameter is documented, so calling it is feasible. But in a suite of ~50 tools with three memory-reading siblings, the absence of any routing or prerequisite information leaves a real gap.

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

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

Schema coverage is 0%, so the description must explain the single parameter, and it does well: default of 100, None meaning full content, and the small-value tradeoff for summaries. Only the interaction with the 'possibly truncated' return is left implicit.

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 ('Read project memory'), so the intent is unambiguous. However, it does not distinguish itself from close siblings like read_memory_section, read_memory_index, or search_memory, leaving the agent to guess which one to call.

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 only guidance ('use smaller values for quick summaries') concerns how to set max_lines, not when to choose this tool over read_memory_section or search_memory. No prerequisites (e.g., that a project root must be set) or exclusion conditions are given.

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 output scope ('just the section headings' plus a 'short tip') and a performance trait ('cheap scan'), but it does not explicitly state read-only semantics, missing-file behavior, or error handling.

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 two sentences, front-loaded with what the tool returns and then the recommended follow-up. Every sentence adds useful routing or scoping information 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?

For a zero-parameter read tool with an output schema, the description gives enough context to call it correctly: what it returns, why it is cheap, and when to use the expansion sibling. Missing-file edge behavior is a minor omission but not necessary 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?

The tool has zero parameters, so the schema baseline is 4. The description appropriately adds no parameter guidance because there is nothing to configure.

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: 'Returns just the section headings from `.ai/memory.md` plus a short tip.' It clearly distinguishes this index scan from `read_memory_section` and from the broader `read_memory` sibling by emphasizing that it returns only headings.

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 this for an 'initial cheap scan' and then call `read_memory_section(name)` to expand only the needed section. This gives both the condition for using this tool and the named alternative for follow-up.

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 truncation behavior and the case-insensitive heading matching, but it does not state what happens when the section is missing, whether the tool is strictly read-only, or any permission/side-effect details.

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 return behavior, followed by compact parameter notes. Every line earns its place with no restating of the tool name 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?

For a low-complexity read tool with an output schema, this covers the essential call semantics. The main remaining gap is what happens when the requested section does not exist, which matters for correct agent behavior.

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, and it does: section_name is documented as a case-insensitive heading without a leading `#`, and max_lines is explained as the body line limit with truncation behavior. It could have mentioned the default value of 200, but otherwise it adds real meaning 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?

States a specific verb and resource: returns the contents of a single `## Heading` section from memory.md. That scope (single section) distinguishes it from siblings like read_memory and read_memory_index, though it doesn't name 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 only implied by the scope: an agent can infer this is for reading one section rather than the whole memory file. There is no explicit statement of when to prefer this over read_memory, search_memory, or read_memory_index, and no exclusions or prerequisites are given.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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, and it discloses the non-obvious side effect that the summary becomes BM25-searchable content — behavior an agent could not infer from the schema. It also states the return shape ('confirmation with annotation coverage stats'). The notable omission is what happens on re-save: whether an existing annotation is overwritten, merged, or rejected, which matters for a mutation tool with zero 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?

Purpose is front-loaded in the first line, the BM25 rationale earns its sentence because it explains why the summary quality matters, and the Args block stays tight. The Returns line is somewhat redundant given an output schema exists, and the docstring formatting adds light structural overhead.

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 3-parameter write tool with an output schema and no annotations, the description covers purpose, mechanism, invocation trigger, per-parameter guidance, and return shape — enough to call it correctly. The one gap an agent would still hit is overwrite/idempotency semantics when an annotation already exists for the path.

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 compensates fully for all three parameters: path is scoped ('relative to project root, or absolute inside it'), summary has a length and content spec ('1-3 sentences: purpose, key responsibilities, notable design'), and keywords explains both format (comma-separated) and strategy (synonyms, domain words not present in identifiers). This adds meaning well beyond the bare string types in 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 ('Saves an AI-authored annotation (summary + keywords) for a source file') and adds the mechanism that makes it distinct: the summary is indexed into BM25 so natural-language queries match it. It never names the sibling it complements (get_annotations, list_unannotated_files), so the read/write pairing must be inferred from the names.

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?

'Write annotations for files you have just read or changed' gives a concrete trigger condition, which is real usage guidance rather than a restatement of the name. There is no exclusion guidance (e.g. skip generated/vendored files) and no pointer to list_unannotated_files as the way to find candidates.

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 mutation profile. It says conventions are saved automatically and a confirmation is returned, but it omits whether existing memory.md content is overwritten, merged, or preserved, and any permission or project-root prerequisites.

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, with no filler. The 'Returns' sentence is somewhat redundant given an output schema exists, but it does not bloat the definition.

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-argument tool with an output schema, the description covers the essential action and result. However, it leaves out how saving interacts with existing memory content and when to prefer it over related memory or convention tools, so it is adequate rather than 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?

There are zero parameters, so the schema has nothing to explain; the baseline for 0 params is 4. The description does not need to add parameter 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 names a specific action (detect and save project conventions) and the target artifact (memory.md), so the purpose is clear. It does not explicitly contrast itself with detect_project_conventions, but the save/persist framing differentiates it reasonably.

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 reason to use it—persisting conventions so assistants avoid re-scanning—but no explicit guidance on when to choose it over detect_project_conventions or update_memory. No exclusions or prerequisites are 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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 only lists what the tool finds and what it returns; it does not state that the operation is read-only, does not mention any rate limits, permissions, side effects, or error behavior. For a search tool, the read-only nature is implied but not disclosed.

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

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

The description is front-loaded with purpose, followed by a scannable bullet list of findings, then Args and Returns sections. It is appropriately sized. The 'Returns' section is somewhat redundant because an output schema exists, but it adds a one-line summary of what to expect.

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 tool's complexity (2 params, output schema present, no annotations), the description covers purpose, findings, and parameter meanings adequately. However, it does not help the agent choose between this and the many sibling search tools (search_codebase, search_with_dependencies, search_for_feature, etc.), which is a significant gap for correct tool selection.

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: 'component' is explained with examples ('auth', 'database', 'api'), and 'n_results' is described with its default (10). Both parameters are given meaning beyond their bare titles, though no format constraints or edge cases are mentioned.

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 verb+resource: 'Specialized search for understanding architecture' and enumerates the specific things it finds (core modules, dependencies, config, patterns). It does not name or distinguish itself from sibling search tools like search_codebase or search_with_dependencies, so an agent still has to infer differentiation.

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 'for understanding architecture' and the list of findings, giving a context cue. However, there is no explicit when-to-use guidance, no when-not conditions, and no mention of alternatives among the many sibling search tools. The agent must infer that this is the architecture-focused search.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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