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

With no annotations, the description carries the full burden. It discloses key behaviors: its scope ('every file and line'), its purpose ('prevents orphaned code'), and an additional warning behavior for low usage. It lacks details on return format or potential performance implications, but for a read-only analysis tool, the disclosed behaviors are sufficient.

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 three sentences, front-loaded with the core purpose and usage context. Every sentence adds value, with no waste or redundancy. The structure is efficient and scannable.

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

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

The tool has two parameters, no annotations, and no output schema. The description covers the tool's purpose, usage timing, and an additional behavior, which is adequate for an agent to invoke it. It does not explicitly describe the return format, but this is inferable from the described tracing 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 100%, with both parameters having clear descriptions. The description adds no parameter-specific guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states a specific action ('Traces every file and line where a specific symbol is imported or used') on a specific resource (symbols across the codebase). It also frames the tool's purpose in context ('Before deleting or modifying code') and differentiates it from general search/deps tools by focusing on blast radius and orphaned code prevention.

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

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

The description explicitly states when to use the tool: 'Before deleting or modifying code, check the BLAST RADIUS.' It also adds a secondary use case for low-usage symbols. However, it does not name alternative tools or specify when NOT to use it, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the output is a 'tiny' summary with 'line-range summaries,' but doesn't mention side effects, permissions, or behaviors when no path is given (e.g., limit default). This is adequate but not rich.

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

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

The description is two sentences with a clear action verb and no fluff. The second sentence provides useful usage guidance without redundancy, and it is front-loaded with the primary action.

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 read-only tool with two optional params and no output schema, the description gives purpose and usage, but omits details like default limit behavior and output format. It is adequate but could be more thorough.

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

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

Schema description coverage is 100%, with both params (path and limit) described in the schema. The description adds only that the file scope is optional, which is already in the schema, so the baseline of 3 applies.

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

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

The description clearly states 'Return a tiny git change summary' with a specific verb and resource, and distinguishes from siblings by noting 'instead of broader repository search.' It also mentions the optional file scoping, making the purpose unambiguous.

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

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

It explicitly says 'Use this for exact changed-file inspection and line-range summaries instead of broader repository search,' providing clear usage context and an alternative category. However, it does not name a specific sibling tool, so it stops short of full when/when-not guidance.

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

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

The description discloses several important behaviors beyond a simple write operation: it validates against specific formatting rules (2-line header comments, FEATURE tags, max nesting depth, max file length), creates a shadow restore point before writing, and rejects non-conforming code. With no annotations provided, the description fully carries the transparency burden and does so thoroughly.

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 the primary purpose. Every sentence adds distinct value: exclusivity claim, validation rules, restore point behavior, and rejection outcome. The use of ALL-CAPS for key phrases ('ONLY' and 'REJECTS') emphasizes critical points without unnecessary words.

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 2-parameter tool with no output schema, the description covers all essential context: validation rules, safety mechanism (shadow restore point), and failure behavior (rejection). It gives the agent a complete mental model of what happens when the tool is invoked, including edge-case handling.

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

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

The schema already provides 100% coverage with clear descriptions for both parameters (file_path and new_content). The description adds no additional parameter-specific details beyond what the schema states. Since the schema handles parameter semantics effectively, baseline 3 is appropriate.

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

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

The description states a clear, specific purpose: 'The ONLY way to write code.' It identifies the resource (code files) and the action (write/save), and differentiates from siblings like restore and lint by claiming exclusivity for write operations. It further clarifies the validation function, making the tool's role unmistakable.

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

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

The phrase 'The ONLY way to write code' is an explicit when-to-use directive. It signals that this is the required tool for any write action, implicitly excluding alternatives for the same operation. While it doesn't name alternative tools, the absolute wording provides strong guidance and distinguishes clear usage context.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states that clusters are 'persisted' and rendered from the 'full index' rather than 'recomputing them on demand', indicating a read-only operation on precomputed data. It does not mention potential side effects, authentication, or failure modes, but the core behavior is 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?

The description is two sentences, front-loaded with the core verb and purpose, and every phrase adds value. It avoids fluff and is easy to scan.

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 simplicity (2 optional parameters, no output schema, no annotations), the description is fairly complete: it states the purpose, the data source, and the behavior. It does not explain the return format in detail, but mentions the key outputs. Minor gaps like error handling or index staleness are not addressed, but for a browsing tool this is acceptable.

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

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

The input schema already documents both parameters (max_depth and max_clusters) with clear descriptions. The tool description does not add additional parameter-level detail, but it does contextually imply they control rendering depth and breadth. Schema coverage is 100%, so the schema carries the load.

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

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

The description clearly states a specific verb ('Browse') and resource ('codebase by MEANING') and lists concrete outputs ('semantic clusters, subsystem summaries, and related-file neighborhoods'). It also distinguishes itself from directory structure navigation, contrasting with sibling tools like 'tree'.

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 on when to use the tool: when you want to explore by meaning rather than directory structure. It implies the alternative (use directory structure, e.g., 'tree') but does not explicitly name other tools or state when not to use it. The mention of 'persisted' and 'full index' hints that the index should be built.

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 transparency burden. It does disclose the output's compactness and the direct/reverse dependency scope, but it does not mention error handling (e.g., what if the file is not indexed), whether the operation is read-only, or any potential side effects. This is partial disclosure, not complete.

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 exactly two sentences: the first front-loads the action and object, the second provides a concise usage directive. No redundant wording or filler.

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

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

The tool is simple (only 1 parameter, no output schema), but the description omits the exact return format (only says 'compact') and does not address edge cases like missing index or invalid target. Since there is no output schema, the description should have provided more detail about the response structure to be truly 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 100% for the sole parameter 'target,' which is already well described in the schema. The tool description adds no extra parameter semantics, so the baseline score of 3 applies.

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

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

The description clearly states the action ('Return') and resource ('compact direct and reverse dependency information for one indexed file'). It also differentiates from siblings by explicitly contrasting with 'broader related search,' making its purpose distinct from tools like 'search'.

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

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

The description explicitly instructs when to use this tool: 'Use this for exact dependency tracing instead of broader related search.' This provides both a clear use case and an alternative, giving an agent strong guidance on selecting it over rivals.

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 core behavior (running benchmark scenarios and reporting metrics) but does not mention potential side effects, performance implications, or prerequisites such as whether an index must be built first. This is a modest gap for a benchmark 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 a single sentence but efficiently packs two logical parts: the scenarios covered and the metrics reported. It is front-loaded with the main action and contains no fluff or redundant phrasing.

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 has no parameters and no output schema, the description adequately explains what it does and what it returns (metrics list). It could further clarify whether output is a JSON object or if any setup is required, but overall it is contextually sufficient for a complex tool.

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

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

The tool has zero parameters, and the schema property list is empty, so there is no parameter information to add. The description correctly omits parameter details, which is appropriate for a tool with no inputs. Baseline for 0 params 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 clearly states the tool runs a built-in real benchmark harness across specific named scenarios (small, medium, monorepo, polyglot, ignored-tree, broken-state, rename-freshness) and reports concrete metrics. This specific verb+resource combination distinguishes it from sibling tools like 'validate_index' or 'search'.

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 the tool: for benchmarking accuracy, validation rates, freshness reliability, and latency. While it doesn't explicitly name alternative tools or exclusions, the context is clear that this is for evaluation/measurement, not for direct operations like indexing or searching.

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 of behavioral disclosure. It explains the tool's read-only navigation behavior, multiple modes, and what each mode produces (list, show skeletons, rank candidates, find orphans). It does not detail return formats or edge cases, but for a navigation/search tool this is adequate.

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 but dense, fitting four usage modes plus a purpose statement into a few sentences. It is structured with numbered modes, making it easy to parse. Slightly long but every sentence earns its place.

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

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

Given the tool's complexity (5 parameters, 4 modes, no output schema, no annotations), the description covers all modes, parameter relationships, and intended outcomes. It does not explicitly describe the return format, but the mode descriptions imply what is returned. Sufficiently complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds valuable inter-parameter semantics: hub_path and feature_name are alternative ways to select a hub, query is used with ranking_mode, and show_orphans is a standalone mode. It also explains defaults (ranking_mode defaults to both) and behavior expectations.

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

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

The description clearly identifies the tool as an 'Obsidian-style feature hub navigator' that works with .md files containing wikilinks. It specifies distinct modes (no args, hub_path/feature_name, query, show_orphans), which differentiates it from sibling tools like tree, deps, or search.

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

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

It provides explicit mode-based usage: no args for listing all hubs, hub_path/feature_name for showing a hub, query for ranking, and show_orphans for finding unlinked files. It also explains intent ('prevents orphaned code and enables graph-based codebase navigation') but does not directly compare to sibling tools or state when not to use it.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool writes to a durable SQLite substrate at .scplus/state/index.sqlite, persists various artifacts (project config, stage state, indexing status, caches, restore points, indexes), and that full mode persists additional artifacts. It also notes 'no JSON mirrors,' a specific behavioral trait. This goes beyond simple 'indexes the repo' and gives a clear picture of 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 a single, dense, run-on sentence that combines many details. While every clause adds relevant information, it lacks clear structural breaks (e.g., separate sentences or bullets) that would improve readability. It is not overly long, but the phrasing 'and in full mode also persists...' could be better organized.

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 (multiple artifacts, modes, persistence details) and the absence of an output schema and annotations, the description provides a thorough account of what happens and where. It explains the two modes, storage location, and what is persisted. However, it does not mention return values or error conditions, but for an indexing tool this is a minor 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?

The input schema has full coverage (100%) with mode's enum and description, so baseline is 3. The description adds significant value by explaining that mode defaults to full and that full mode persists chunk and code-structure artifacts with contract metadata. This clarifies the practical difference between core and full beyond the schema's simple enum.

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

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

The description clearly states the tool's function: 'Create or refresh the .scplus project state for this repo.' It specifies a concrete action (create/refresh), a specific resource (.scplus project state), and the scope (repo-local). This distinguishes it from sibling tools like status, validate_index, and repair_index, which operate on or query existing state rather than building it.

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: run this to (re)build or refresh project state, but it does not explicitly state when to use this vs. alternatives. It does not mention that status, validate_index, or repair_index are for checking or fixing an existing index, nor does it provide when-not-to-use guidance. Thus, usage context is present but relies on 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 present, so the description carries the burden. It discloses that the tool delegates to native linters/compilers and supports multiple languages, but it does not mention potential side effects, requirements (e.g., installed linters), output format, or whether it is read-only. This is partial 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?

The description is three sentences, front-loaded with action and resource, and every sentence adds value: purpose, deterministic approach, and supported languages. No redundancy or waste.

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

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

For a tool with no output schema, the description fails to explain what the tool returns (e.g., diagnostics, exit codes, formatted report). It is adequate for selection but incomplete for understanding results. Given minimal schema and annotations, this is a notable gap.

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

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

The schema already covers the parameter completely (100% coverage) with a clear description. The tool description adds language support details (TypeScript, Python, Rust, Go), which clarifies valid values for target_path and thus adds meaning beyond the schema.

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

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

The description uses a specific verb ('Run') and resource ('project's native linter/compiler'), and clearly states the types of issues found (unused variables, dead code, type errors, syntax issues). It also distinguishes the tool from siblings by emphasizing deterministic delegation over LLM guessing, and lists supported languages.

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 the tool: whenever deterministic linting/compilation is needed, explicitly contrasting with LLM guessing. This gives clear context for selection, though it does not mention specific alternatives or when not to use it.

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

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

With no annotations, the description must communicate behavioral traits. It mentions the 'prepared fast-query substrate,' hinting that the file must be indexed, but it doesn't explain what happens if the file is not indexed or how errors are handled. The read-only nature is implied but not explicitly stated.

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

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

Two concise sentences: the first states the primary action and result, the second gives the use case. No filler or repetition. Front-loaded with the verb and object.

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 single-parameter tool with no output schema, the description covers what it does, when to use it, and what the outline contains. It does not explicitly state that the file must be indexed beforehand, but the phrase 'prepared fast-query substrate' partially implies it. Overall, quite complete for its complexity.

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

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

The schema description coverage is 100%, so the schema already documents the file_path parameter well. The tool description adds no further parameter-level details beyond the schema's own description. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Return') and resource ('compact file outline'), and clarifies the content (imports, exports, symbols). It distinguishes itself from sibling tools by explicitly noting this is for a known file and avoids broader search or full-body reads.

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 a clear 'when to use' statement ('when you know the file and want imports, exports, and symbols') and implies exclusions ('without broader search or full-body reads'). However, it does not name alternative tools explicitly, which would have earned a 5.

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

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

No annotations are provided, so the description must carry the burden. It discloses that the operation reruns pipeline/stages and then validates, but does not mention potential destructive effects, permissions, reversibility, or what 'durable stage' means. This is moderate transparency but leaves gaps about 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?

One concise sentence that front-loads the purpose and method. Every word earns its place; no filler or repetition.

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

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

The tool is simple with one parameter and no output schema. The description covers the action and validation step, but lacks explicit mention of return values or post-conditions. Given the schema and sibling context, it is nearly complete but could add a note about what the validation returns.

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

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

Schema coverage is 100%, and the schema describes the 'target' parameter well. The tool description adds no extra parameter details beyond the schema, which is acceptable given the high coverage. The baseline of 3 applies.

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

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

The description clearly states the action: repair the prepared index, and the mechanism: rerunning the full pipeline or a specific durable stage, followed by validation. This distinguishes it from sibling tools like 'index' (build), 'validate_index' (validates), and 'status' (informs).

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 the tool is used when an index needs repair and offers a choice between full pipeline or specific stage rerun. The schema description reinforces this with 'Use core/full for full pipeline rebuilds or a stage name for a targeted rerun.' It lacks explicit exclusions or comparisons to alternatives, but the 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 carries the full burden. It discloses that it aggregates multiple sources into a bounded report, which is helpful. However, it doesn't mention whether the operation is read-only, potential cost/latency, or what 'bounded' precisely means, leaving some behavioral ambiguity.

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

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

Two sentences with no fluff. The first sentence front-loads the core action and output; the second provides usage context. Every word earns its place.

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

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

For a single-parameter tool with no output schema, the description explains what is aggregated and when to use it. The output is described as a 'bounded report', which is sufficient at a high level, though 'bounded' is somewhat ambiguous and could benefit from clarification on size or scope.

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 input schema covers the single parameter 'query' with a clear description, so baseline is 3. The tool description reinforces that the query is for broad subsystem understanding, but adds no additional parameter details beyond what the schema already provides.

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

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

The description clearly states the tool's function: it aggregates ranked code retrieval, related files, subsystem summaries, and relevant hubs into a bounded report. It distinguishes itself from sibling tools by positioning it for broad subsystem understanding after exact lookup or related-item search fails, which is a specific and differentiated purpose.

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

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

The description explicitly says to use this when exact lookup or related-item search is no longer enough, providing clear when-to-use guidance. It doesn't name specific sibling tools, but it gives a strong contextual signal that this is for broader understanding, which effectively guides tool 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?

No annotations are provided, so the description must carry the full transparency burden. It does disclose one key behavioral trait: 'Does NOT affect git history' and references the 'shadow restore point system.' However, it does not clearly state that this is a mutating operation that will overwrite current files, nor does it mention reversibility or side effects beyond git. This adds some context but is insufficient for a write operation.

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

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

Three short sentences, each earn their place. The first sentence states purpose, the second explains the system behavior, and the third gives a clear prerequisite. No fluff or repetition.

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

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

For a single-parameter tool with a clear schema and prerequisite, the description is mostly complete. It covers purpose, usage prerequisite, and a key non-effect (git). It does not mention what the return value looks like or potential destructive consequences, but given the simple tool shape, these are minor omissions.

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

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

The schema covers 100% of parameters with a description for point_id ('The restore point ID (format: rp-timestamp-hash). Get from restore_points.'). The tool description repeats this guidance ('Call restore_points first'), adding no new syntax or format details. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's action ('Restore files'), the specific scope ('to their state before a specific AI change'), and the mechanism ('shadow restore point system'). It distinguishes from siblings like restore_points (which lists points) and checkpoint (which creates points).

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 explicit prerequisite guidance: 'Call restore_points first to find the point ID.' This clearly instructs when to use this tool relative to its sibling. It also notes a caveat ('Does NOT affect git history') that helps decide between restore and git-based alternatives. Absence of explicit 'when not to use' is a minor gap.

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. It explains that points capture state before AI changes, which adds context. However, it doesn't explicitly state whether this is a read-only operation or disclose any side effects, order, or other behavioral details that would enrich transparency.

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 concise, information-dense sentences. The first states the action and source; the second explains the purpose and usage. No wasted words.

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 list tool with no output schema, the description is sufficient to understand the purpose and how to use the result. It lacks explicit return format or ordering details, but these are minor for a simple listing tool.

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

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

The tool has 0 parameters, so the schema coverage is 100% by default. The description adds meaning by explaining what a restore point is and how it relates to the 'checkpoint' tool, which is useful despite having no params to document.

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 ('List') and resource ('shadow restore points'), and clarifies it is a read operation for finding restore point IDs. This clearly distinguishes it from the sibling 'restore' tool which actually performs the restoration.

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 states when to use this tool ('Use this to find a restore point ID for undoing a bad change'), providing clear context. It doesn't explicitly contrast with alternatives, but the purpose implies the distinction from 'restore'.

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 burden of behavioral disclosure. It mentions that 'exact' is a deterministic fast lookup and 'related' operates over 'prepared full-engine artifacts', offering some insight into behavior. However, it does not describe potential side effects, prerequisites like index readiness, or failure modes.

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

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

The description is two sentences, front-loaded with the core routing concept, and contains no unnecessary verbiage. Every phrase contributes to understanding the tool's function and usage.

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 six parameters and no output schema, the description is too sparse. It does not explain what results look like, whether an index must be built first, or how retrieval_mode relates to the 'related' intent. This leaves important gaps for an agent to correctly invoke the tool.

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

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

The input schema covers all parameters with descriptions, so the baseline is 3. The description adds a bit of extra meaning for the 'intent' parameter by elaborating on exact versus related behavior, but other parameters are already well-documented in the schema and need no further clarification.

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

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

The description clearly identifies this as a repository search tool and explains the two intent modes: exact for deterministic symbol/file lookup and related for ranked pattern discovery. It is specific about the resource and behavior, though it does not explicitly differentiate from sibling tools like 'symbol' or 'research'.

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

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

The description gives explicit guidance on when to use each intent: use 'exact' when you know the exact symbol or file target, and 'related' for ranked related-item discovery. This is clear context for choosing the right mode, though it does not mention when to prefer this tool over alternative sibling tools.

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

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

With no annotations, the description carries the full burden. It discloses that the tool does NOT read the full body, and it specifies the exact output elements (function names, parameters, return types, line ranges). This is transparent about its behavior, though it doesn't mention error handling or behavior on non-code files.

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

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

The description is two sentences, front-loaded with the main action and outcome. No filler words; every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the return content (function signatures, methods, types, line ranges) and the key constraint (not reading full body). It lacks details about edge cases, but for the tool's simplicity, it's nearly complete.

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

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

The single parameter 'file_path' is fully described in the schema (100% coverage), so the description doesn't add much parameter-specific meaning. It simply refers to 'specific file' which is redundant with the schema. Baseline of 3 is appropriate given schema completeness.

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

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

The description clearly states the tool's function: extracting function signatures, class methods, and type definitions from a file without reading the full body. It distinguishes itself from siblings like 'symbol' and 'outline' by emphasizing the API surface focus and the explicit avoidance of loading full file contents.

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 a clear use case: 'Perfect for understanding how to use code without loading it all.' However, it does not explicitly mention alternatives or situations where another tool would be more appropriate, so it misses the 'when-not' guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. The word 'Return' implies a read-only operation, and 'tiny' suggests a concise summary, but it does not explicitly state that it makes no modifications, nor does it mention what happens if the current directory is not a git repository. This is adequate but leaves some gaps.

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

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

The description is two sentences, front-loaded with the core action, and includes a usage direction. Every word earns its place with no redundancy or fluff.

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 tool with one parameter and no output schema, the description covers the purpose, when to use it, and hints at output content ('branch and dirty-file checks'). It does not detail the exact output format or edge cases, but that is acceptable given the tool's low complexity.

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

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

The schema already provides full coverage for the single parameter ('limit' with description and default). The description does not add any additional parameter semantics, which is acceptable given the 100% schema coverage. Baseline of 3 is appropriate.

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

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

The description states a specific verb ('Return') and a specific resource ('tiny git worktree status summary') with a defined scope ('current repository'). It also distinguishes from sibling tools by explicitly saying 'for branch and dirty-file checks instead of reading broader change context', which differentiates it from 'changes'.

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 when to use the tool ('for branch and dirty-file checks') and an explicit exclusion ('instead of reading broader change context'). However, it does not name the alternative sibling tool (e.g., 'changes') directly, so it falls just short of full explicit alternative guidance.

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

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

No annotations are present, so the description carries the burden of behavioral disclosure. It adds 'exact', 'deterministic', and 'tiny' qualifiers, and hints at a prerequisite with 'prepared fast-query substrate', but it does not explain failure modes, return behavior when no match exists, or whether the substrate must be explicitly indexed.

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

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

The description is two sentences, front-loaded with the action and followed by usage guidance. Every word contributes to understanding the tool's purpose or selection criteria, with no fluff.

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 lookup tool with full schema coverage and no output schema, the description covers purpose, usage, and key behavioral traits. The only minor gap is the unexplained 'prepared fast-query substrate', but the tool is simple enough that the description is nearly complete.

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

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

The input schema provides full descriptions for both parameters (query and top_k), so schema coverage is 100%. The description adds no additional parameter-level detail beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description states the tool runs an exact symbol lookup against a prepared fast-query substrate, using a specific verb and resource. It also contrasts this with ranked related search, distinguishing it from the likely 'search' 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?

Explicitly tells the user when to use this tool: when the exact symbol name is known and deterministic exact matches are needed, instead of ranked related search. This provides clear selection criteria relative to alternative search behavior.

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 present, so the description carries the transparency burden. It discloses non-obvious behaviors: automatic reading of 2-line headers and dynamic token-aware pruning with three levels. This provides meaningful insight beyond the basic 'get' action.

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 concise sentences: the first states the core purpose and output content, the second clarifies the automatic header reading and pruning behavior. No wasted words, well front-loaded.

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

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

The description covers the tool's output content and adaptive behavior, sufficient for a read-only structural tool with fully described optional parameters. Without an output schema, it gives enough about return values (symbols, headers, line ranges) to guide the agent.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the adaptive pruning mechanism (Level 2 to 0) which connects to max_tokens and include_symbols, giving context on how parameter choices affect output detail.

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

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

The description clearly identifies the tool's purpose: returning a structural tree of the project with file headers, function names, classes, enums, and line ranges. The specific verb "Get" plus resource details distinguishes it from siblings like outline or skeleton.

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 implies when to use the tool (to inspect project structure at varying levels of detail) and notes behavior based on project size. However, it does not explicitly contrast with alternatives like outline or skeleton, nor mention when not to use it.

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

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

No annotations are provided, so the description must carry the full burden of transparency. While 'validate' implies a read-only operation, it does not explicitly state whether it modifies anything, whether it requires specific permissions, or what happens on failure. The description focuses on what is checked, not on the tool's side effects or outcomes.

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

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

The description is a single concise sentence that immediately states the purpose. It contains no filler and is appropriately sized for the tool's low complexity.

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?

Despite the tool's low complexity, the description is incomplete. Since there is no output schema, it should at least mention what the tool returns (e.g., pass/fail, error details, validation report) or how the result is communicated. It also omits behavioral details like side effects, making it insufficient for an agent to fully anticipate the tool's 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 100% because the only parameter 'mode' is fully described in the schema. The description repeats the mode options ('core or full mode') but adds no additional meaning beyond the schema, so it provides no extra value here.

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

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

The description clearly states the tool's function: 'Validate that the prepared sqlite-backed index is present, version-compatible, and internally consistent.' It specifies the verb (validate), resource (sqlite-backed index), and scope (presence, version compatibility, consistency), which distinguishes it from siblings like 'repair_index' and '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?

The description gives no guidance on when to use this tool versus alternatives like 'repair_index' or 'status.' It does not mention prerequisites (e.g., that the index must be prepared already) or typical use cases, leaving the decision of when to invoke it unclear.

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 burden. It discloses the tool is lightweight ('tiny'), indexed, and searches specific content types, adding context beyond the schema. Minor gaps remain (e.g., matching behavior, no result handling), but for a simple lookup tool this is adequate.

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

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

Two sentences, front-loaded with a clear verb, and no wasted words. Each sentence provides distinct value: what it does and when to use it.

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

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

For a tool with only 2 parameters and no output schema, the description covers functionality, scope, and usage guidance. It does not explain return format, but the simplicity of the tool and sibling context (e.g., search) make it sufficiently 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 coverage is 100% with both parameters adequately described. The description reinforces 'word or short phrase' but adds no new semantic detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific action ('Run a tiny indexed word lookup') and defines the exact scope ('over paths, headers, symbols, and content snippets'), clearly distinguishing it from broader sibling tools like search.

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

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

Explicitly instructs when to use it ('for exact words or short phrases') and when not to ('before escalating to broader ranked search'), providing clear guidance relative to alternatives.

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