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 tool is read-only ('Read the local database schema snapshot') and that it requires no DB connection. It does not mention error handling if the snapshot is missing, but overall behavior is well explained.

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, no fluff, front-loaded with the core purpose. Every word adds value—purpose, return types, source, and prerequisite are all covered efficiently.

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

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

For a read-only tool with 4 optional parameters and no output schema, the description adequately covers purpose, source, prerequisite, and return contents. It lacks detail on the return structure format, but the listed items give sufficient context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond what the schema already provides for each parameter.

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?

Description clearly states the verb 'Read' and the resource 'local database schema snapshot', and enumerates what is returned (tables, columns, etc.). This distinguishes it from sibling tools like db_snapshot (which creates the snapshot) and db_search (which searches within the db).

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?

Description mentions the prerequisite 'Run db_snapshot first' and clarifies that no DB connection is needed, implying when to use. It does not explicitly state when not to use or list alternatives, but the context is clear given sibling names.

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 full burden. It discloses a key behavioral trait (searches a local snapshot, no DB connection), but does not mention other details like search accuracy or potential limitations.

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 with two sentences and examples. It is front-loaded: first sentence states the purpose, second adds a key constraint. The examples are helpful but could be integrated more smoothly.

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 core functionality and the offline nature, but it does not describe the output format (e.g., list of tables/columns) despite having no output schema. Completeness is adequate for a simple search tool but not exceptional.

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 parameter descriptions. The tool description reinforces the query parameter with concrete examples (e.g., 'tables related to authentication'), adding meaning beyond the schema. The limit parameter is adequately covered.

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 searches the database schema by natural language query to find tables and columns matching a concept. It includes concrete examples and distinguishes itself from siblings by noting it uses a local snapshot without a DB connection.

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 concept-based schema search) and an important constraint (no DB connection), but it does not explicitly state when not to use it or compare with siblings like db_schema or search_code.

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 full burden. It discloses output file path, connection mechanism, supported DB, fallback, and optional save flag. Does not explicitly state read-only nature, but 'introspect' implies no mutation. Good but could be more 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?

Two sentences, front-loaded with purpose, no redundant information. Every sentence contributes useful detail.

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 4 parameters, no output schema, and no annotations, the description covers purpose, parameters (with context), usage, output file path, and relationship to sibling tools. It is fully adequate 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%, baseline 3. Description adds meaning: connection_string has env var fallback; provider is an enum with auto-detect; schemas has default and Supabase hint; save_connection explains its purpose. Adds value beyond 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 clearly states the tool's purpose: introspect a database and save a local schema snapshot to a specific file. It also distinguishes it from sibling tools by noting it should be run once before using db_schema or db_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?

Provides clear context: run this once before using related tools. Describes fallback behavior (connection string or local files). Lacks explicit exclusions or alternatives, but the context is adequate.

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 full burden. It discloses the heuristic nature, thresholds, and that it returns a boolean and signals. However, it omits details on error handling, side effects, and the meaning of 'No API', leaving room for 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?

The description is three sentences, each essential: purpose, logic, and usage context. It is front-loaded with the main verb and resource, and contains no superfluous 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?

Given the lack of an output schema, the description partially explains return values but does not detail the 'signals' output or potential error conditions. More information on the output format would improve completeness.

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 each parameter having a description. The tool description repeats default values but adds no new meaning beyond what the schema already provides, so 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 clearly defines the tool's role as a heuristic detector for session technical significance, specifying criteria (git diff thresholds, graph cycles) and output (significant:true + signals). It is distinct from sibling tools, which focus on code analysis and project health.

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 the intended use in Stop/SessionEnd hooks and integration with storeMemory. However, it does not discuss when not to use the tool or mention alternative tools, which would strengthen 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?

Without annotations, the description adds value by mentioning the prerequisite 'Requires a prior reindex' and the backtick-quoted identifier mechanism. However, it does not disclose error behavior, side effects, or whether it is read-only. Some behavioral context provided but incomplete.

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 sentences, front-loaded with purpose, then use cases, then prerequisite. No wasted words. Each sentence earns its place.

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

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

The description explains what the tool does and its prerequisite but does not describe the output format (e.g., list of files, snippets). Given no output schema, the agent would benefit from knowing return structure.

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

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

Schema coverage is 100% so baseline is 3. The description adds that identifiers are backtick-quoted and implies mutual exclusivity between symbol and file. This adds modest value beyond the schema descriptions.

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 verb 'find' and the resource 'documentation/markdown files that reference a code symbol or file', and differentiates from siblings by specifying backtick-quoted identifiers and use cases like checking before deletion.

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?

Provides explicit when-to-use scenarios (discover documentation, check before deletion) and a prerequisite (prior reindex). Lacks explicit when-not-to-use but context implies alternatives may exist.

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 full burden. It discloses the algorithm ('Uses BFS on the dependency graph'), output components ('severity assessment, impacted files by depth, and edges'), and a behavioral trait ('No API call needed'). This is highly transparent and adds significant value beyond what annotations could provide.

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 each sentence adds distinct value. No unnecessary words or redundancy. Highly efficient.

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 no output schema, the description covers return values (severity, impacted files, edges). It also includes prerequisite and algorithm. For a 2-param tool, this is nearly complete; minor gap is lack of explicit differentiation from 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?

Input schema has 100% coverage (both parameters described). The description does not add new semantic information about the parameters; it only mentions depth indirectly via BFS. Baseline score of 3 is appropriate as schema does the heavy lifting and description adds minimal additional meaning.

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

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

The description clearly states the tool's purpose: analyzing blast radius of file changes, finding directly/transitively affected files. It uses specific verbs ('Analyze', 'find') and resource ('file changes'). The tool is well-distinguished from siblings like get_dependencies or get_dependents by focusing on transitive impact and severity assessment.

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 states a prerequisite ('Requires a prior reindex'), which guides when the tool can be used. It does not explicitly list when not to use or name alternatives among siblings, but the context implies it for full impact analysis. A clear usage condition is provided.

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 provided, so description bears full burden. Explains rule file location and format, and glob patterns. Does not cover error cases, what happens with missing/invalid config, or return 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?

Three sentences: purpose, config format, usage tip. Front-loaded and 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?

Given no output schema and no parameters, description covers key aspects: source, format, prerequisite, purpose. Lacks edge cases (missing config, reindex failure).

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?

No parameters in input schema (0 params, schema coverage 100%). Baseline 4 applies; description does not need to add parameter info.

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?

Clearly states it returns architecture boundary violations detected at index time. Distinguishes from sibling tools like get_circular_deps or get_dead_code by focusing on boundary violations.

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

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

Explicitly says to use it to enforce layering rules without runtime overhead, and mentions prerequisite 'Requires a prior reindex.' Lacks explicit when-not-to-use or comparisons to alternatives.

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

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

No annotations provided, so description carries full burden. It states the algorithm used, that no API call is needed, and that it returns cycle groups. Could mention it's read-only, but overall transparent.

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

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

Three concise sentences, front-loaded with the main purpose, followed by usage advice and prerequisite. 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?

Given the tool's simplicity (one optional param, no output schema), the description fully covers what it does, when to use, and what it returns (groups of files). No 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?

The schema already describes the single parameter (max_cycles, default 50) with 100% coverage. The description adds no extra semantic value for this parameter, so baseline 3.

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 detects circular dependencies using Tarjan's SCC algorithm and returns cycle groups. This distinguishes it from sibling tools like get_dependencies or get_most_coupled.

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 a specific use case (before refactoring) and a prerequisite (requires prior reindex). No explicit when-not-to-use or alternatives, but the context is sufficient for basic 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 bears full burden. It discloses exclusions of entry points and the need for reindex, but doesn't describe output format, error behavior, or limitations of the analysis.

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 concise sentences with front-loaded main action. No wasted words; each sentence adds essential information (what, exclusions, usage, prerequisite).

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 no output schema, the description misses details about the return structure (e.g., list of file paths). However, the tool's purpose is well-covered for a simple analysis tool with one optional parameter.

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

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

The single parameter exclude_patterns is described in both schema and description with examples, adding context beyond the schema (e.g., regex patterns for exclusion). Since schema coverage is 100%, this extra context earns a top score.

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 finds files never imported by any other file (dead code candidates). This verb+resource combination is specific and distinguishes it from sibling tools like get_dependencies which focus on dependencies of a given file.

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 to identify unused code before cleanup and notes that prior reindex is required. However, it doesn't contrast with alternatives like usage_anomalies or provide when-not-to-use 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 provided, the description carries the burden of behavioral disclosure. It states 'No API call needed' and the reindex requirement, but does not describe the return format, performance characteristics, or whether it is read-only. For a non-destructive tool, this is adequate but not exhaustive.

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 zero wasted words. It front-loads the core purpose and then adds essential usage context, demonstrating efficient communication.

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 two simple parameters and no output schema, the description covers the main points: purpose, prerequisite, and network behavior. It does not describe the return format (e.g., list of file paths), which would be beneficial but is not critical given the simplicity. Overall, it is mostly 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%, so the schema already explains both parameters ('file' and 'depth'). The description adds no additional meaning beyond what is in the schema, earning the baseline score of 3.

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 ('Get') and describes the resource ('dependencies'). It clearly states it shows the dependency chain from a given file outward, which distinguishes it from the sibling tool 'get_dependents' that shows dependents.

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 specifies a prerequisite ('Requires a prior reindex') and clarifies that no API call is needed, implying it's a fast, local operation. It does not explicitly contrast with siblings but provides context for correct usage.

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 full burden. It discloses that no API call is needed and requires a prior reindex, which are important behavioral traits. No destructive or side effects are mentioned, but the tool is read-only by nature.

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, with three sentences that front-load the purpose and add essential context (prerequisite, no API call). Every sentence contributes meaningfully.

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 is complete: it explains the purpose, the input, the prerequisite, and a behavioral note. No gaps are apparent.

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' is fully described in the schema (100% coverage). The description adds no additional semantic information beyond what the schema provides, so a 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 clearly states the tool returns files that import a given file (dependents/reverse dependencies), distinguishing it from sibling tools like get_dependencies which likely return forward dependencies. It also specifies the prerequisite of prior reindex.

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 mentions a key prerequisite (prior reindex), which guides proper usage. It does not explicitly state when to use this tool over alternatives, but the purpose is clear enough for 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 full burden. It discloses key behaviors: it is AST-based, has a token budget with truncation flag, and returns signatures and JSDoc without bodies. This is thorough and helps the agent understand side effects and constraints.

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 long, front-loaded with 'STEP 3 of token-efficient exploration' to signal context. It is concise and avoids fluff, though it could be slightly more 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?

Given the tool's simplicity (2 parameters, no output schema), the description adequately covers the return content, constraints, and method. It explains what is excluded (function bodies) and fallback behavior, but could mention the return format briefly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about the token budget and file path but does not provide details beyond the schema's parameter descriptions. It references the fallback behavior linked to token_budget, but that is already 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?

The description clearly states what the tool does: returns all symbols with signatures and JSDoc but no function bodies, as a folded view under a token budget. It uses specific verbs ('Returns') and defines the resource ('symbols'), which is clear. However, it does not explicitly differentiate from siblings like get_file_outline or get_symbol, though context from 'STEP 3' implies a sequence.

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 a usage hint ('Ideal when you need to understand a file structurally without reading every implementation') and mentions fallback behavior for budget exceeded. However, it does not specify when not to use this tool or list alternatives, leaving some ambiguity.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool uses AST (not API), outputs approximately 200 tokens, and is part of a multi-step process. It does not cover error handling or edge cases but provides sufficient behavioral context for a simple read-only 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 extremely concise (approximately 60 words) and front-loaded with the most critical information (step, purpose). Every sentence adds value, and directives are clearly marked with attention-grabbing language ('STEP 2', 'NEVER').

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 (1 parameter, no output schema), the description covers purpose, usage context, behavior, and next steps adequately. It could be improved by briefly noting the output format beyond 'lists top-level symbols', but the lack of an output schema makes this a minor gap. The sibling tool context further enriches completeness.

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 has 100% description coverage for its single parameter 'file', which is well-documented in the schema itself. The description does not add new semantic information beyond what the schema states, so 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 clearly states the tool lists top-level symbols (functions/classes/types/hooks) with line ranges and imports/exports, using specific verb 'lists' and resource 'file outline'. It distinguishes from siblings like get_file_folded and get_symbol by positioning itself as step 2 and specifying what it covers.

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 guidance on when to use this tool ('STEP 2 of token-efficient exploration'), when not to use alternatives ('NEVER Read the whole file'), and what to do next ('call get_file_folded for signatures+JSDoc, or get_symbol for full source of ONE symbol'). This is exemplary for directing an AI agent's workflow.

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?

Lacking annotations, the description carries the full burden. It discloses 'No API call needed — instant response', which is a key behavioral trait. However, it does not mention authentication requirements, staleness of results, or impact on state. The mention of 'indexed files' implies a pre-indexed state, adding moderate value.

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, no wasted words. The main purpose and key benefit are front-loaded. 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?

The tool is simple with one optional parameter and no output schema. The description covers what it returns (organized directory, stats). Missing details about the return format (e.g., JSON structure) or potential limitations (e.g., large directories) prevent a perfect score, but overall it is sufficiently complete for a retrieval tool.

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

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

Schema description coverage is 100% (one optional parameter with a description). The description adds no new semantic information beyond the schema's 'Project root path (auto-detected from cwd if not provided)'. Baseline of 3 is appropriate as the description does not enhance understanding of the parameter.

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 verb (Get), the resource (project file tree structure), and what is returned (organized by directory with stats on languages and file counts). It distinguishes from sibling tools like get_file_folded or get_file_outline by specifying the full tree and stats.

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?

No explicit guidance on when to use this tool versus alternatives. The description mentions 'No API call needed — instant response' but does not specify context, prerequisites, or scenarios where other tools would be more appropriate. Given the many sibling tools, this is a significant 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?

No annotations provided, so description carries full burden. It explains the computation (combined in-degree + out-degree), the prerequisite of a prior reindex, and states it's not an API call. This provides good behavioral context beyond schema, though it could mention error handling or performance implications.

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

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

Four concise sentences with no wasted words. The main purpose is front-loaded, and each sentence adds distinct value: purpose, interpretation, prerequisites, and operation mode.

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 a single parameter and no output schema, the description covers purpose, behavior, prerequisites, and interpretation of results. It is sufficiently complete for an agent to understand when and how to use the tool 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 only parameter 'top' is fully described in the input schema (number, default 10, max 100). The description adds no additional meaning about this parameter. With 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?

Description clearly states the tool returns the most highly coupled files, defines coupling as combined in-degree + out-degree, and explains the significance for refactoring. It distinguishes from sibling tools like get_dependencies and get_dependents by focusing on overall coupling rather than per-file relationships.

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 mentions the prerequisite 'Requires a prior reindex' and clarifies 'No API call needed'. While it doesn't explicitly list when not to use or alternatives, the context is clear for an agent.

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 returns 'full source' with context (imports, siblings, warnings) and explains the context parameter. However, it omits details like error handling, idempotency, or what happens if the symbol is not found.

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: the first defines purpose and output, the second gives usage guidance. Front-loaded with the step number. 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?

Given no output schema, the description adequately describes the return (full source with context). It covers the main parameters and usage constraints. However, missing details like error responses or performance implications, but acceptable for a simple retrieval 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%, baseline 3. The description adds value by explaining the context parameter's default (true) and what it includes ('imports, exports, sibling symbols, warnings'), going beyond the schema's brief 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?

The description clearly states the verb 'fetches' and the resource 'ONE symbol (function/class/type)' with file context. It positions itself as 'STEP 4 of token-efficient exploration' and notes it's 'the only step that returns full source,' distinguishing it from sibling tools.

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: 'Use ONLY after `search_code`/`get_file_outline`/`get_file_folded` identified the symbol.' It also says 'No API,' implying it's for in-context code base retrieval, not external APIs.

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 full burden. It states 'No API call needed' and implies a read operation (returns files). It also mentions the reindex prerequisite. While it could detail side effects or permissions, the description is sufficiently transparent for a simple read tool.

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

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

The description is two concise sentences: first states the core function, second explains usage and requirements. No unnecessary words or repetition. It is front-loaded and efficiently communicates key 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?

Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description is complete. It covers purpose, when to use, prerequisite, and that no API call is needed. An agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%: the only parameter 'files' has a clear description in the schema. The tool description adds overall context (reindex, no API) but does not further elaborate on the parameter beyond what the schema provides. 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 clearly states the tool returns files in dependency order (dependencies before dependents), which is a specific verb-resource combination. It distinguishes from siblings like get_dependencies and get_dependents by emphasizing the topological ordering and its use for safe refactor ordering.

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 tells when to use: 'determine the safe order to modify files during a refactor' and mentions a prerequisite ('Requires a prior reindex'). It does not explicitly list alternatives or when not to use, but the context is clear enough for an agent.

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

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

With no annotations provided, the description carries the full burden. It discloses grouping heuristics, output formats, and preconditions. It covers key behavioral aspects without contradiction.

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 that front-load the core purpose, then efficiently detail grouping and formats. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description explains the output behavior (file generation) and covers all parameters, preconditions, and grouping logic. It is complete for an export 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 all parameters. The description adds minimal additional meaning, such as default output path pattern, but does not significantly enrich parameter understanding 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 clearly states the tool exports a static architecture diagram from the dependency graph, with specific grouping and output formats. It distinguishes itself from sibling analysis tools like graph_view or get_dependencies by focusing on export rather than interactive exploration.

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 mentions prerequisite (requires a prior reindex) and includes relevant context about output formats. While no direct comparisons to siblings are made, the description provides sufficient context for when this tool should be used.

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 provided; description fully discloses behavior: opens in VS Code Simple Browser, interactive features (filtering, focusing, clicking), and dependency on reindex. No contradictions.

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

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

Four sentences with no fluff, front-loaded with main action. Every sentence adds value: purpose, features, prerequisite, and output location.

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 single optional parameter and no output schema, description fully covers purpose, behavior, features, and prerequisite. Agent has enough to decide and invoke correctly.

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

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

Schema description coverage is 100%; parameter 'port' is fully described in schema. Description adds no extra meaning beyond schema, meeting baseline of 3.

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?

Description clearly states it launches a 3D interactive dependency graph visualization, distinguishing it from sibling tools like get_dependencies (data) and graph_export (static file). Specific verb 'launch' and resource 'project dependency graph' are 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?

Explicitly states prerequisite: 'Requires a prior reindex to build the dependency graph,' guiding when to use. Implicitly, it's for visual exploration vs. other tools for static analysis, but lacks explicit when-not-to-use.

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?

Discloses the tool runs multiple internal analyses, returns a score A–F, and notes 'No API call needed,' implying it is local and low-cost. No annotations provided, but description is transparent about functionality and cost model.

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, no fluff. First sentence covers what it does, second provides usage guidance. Every word 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?

Given no output schema and no parameters, the description covers the key points: analyses performed, output format, and usage context. Could mention if there are side effects (likely none), but overall 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, and the description does not need to add param semantics. Baseline for 0 params is 4, and the description is sufficient.

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 an aggregated health check with specific analyses (cycle detection, dead code, coupling hotspots, etc.) and returns a global score A–F, distinguishing it from sibling tools that focus on individual analyses.

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

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

Explicitly says 'Use as a quick diagnostic before any major refactoring.' This gives clear when-to-use guidance. It doesn't explicitly state when not to use, but given sibling tool variety, the context implies this is a high-level overview.

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?

Describes incremental behavior, auto-index enablement, and force deletion. No annotations exist, so description covers key behaviors well, though missing rate limits or auth.

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 sentences, front-loaded with main purpose, each sentence adds new information without 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?

Covers use cases and parameter behavior but misses return value description and potential side effects like locking, given no output schema.

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

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

Schema coverage is 100% with moderate descriptions. The tool description adds contextual usage (e.g., 'after switching EMBEDDING_PROVIDER') but mostly reiterates schema info.

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 'Force incremental reindex of the project codebase' with a specific verb and resource, and it distinguishes from sibling 'reindex_file' by focusing on the entire 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?

Provides explicit use cases: initial index, after switching providers with force. Lacks explicit 'when not to use' but implies normal updates are automatic.

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

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

With no annotations provided, the description carries the full burden. It discloses that the operation is faster than a full reindex and requires an API key. It mentions keeping the index up-to-date, but does not detail side effects, idempotency, or error handling. Still, the behavioral context is fairly 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-loads the purpose, and contains no unnecessary 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides sufficient context: purpose, usage hooks, performance note, and a prerequisite. No gaps remain.

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 the single parameter 'file' with a clear description. The tool's description adds no additional parameter detail beyond what the schema provides, so a 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 clearly states the tool's purpose (reindex a single file) and distinguishes it from a full reindex, which is a sibling tool. It specifies the context of use (after modification or creation).

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 ('after Write/Edit tool calls') and implies when not to (not for full reindex). It also notes a prerequisite: 'Requires OPENAI_API_KEY'.

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 tool returns a lightweight index (not full source) and implies read-only behavior. It does not mention auth, rate limits, or cost, but for a search tool this is reasonable. The behavioral traits are well explained.

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 purpose, then condensed usage workflow. Every sentence is purposeful: first sentence defines what it does, second provides an efficient exploration strategy. 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?

Despite no output schema, the description explains return format (file paths, line numbers, short previews) and integrates with sibling tools. It addresses the broader context of token-efficient code exploration, making it complete for its role.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not repeat schema details but adds context on how to use extensions to exclude content files, which adds value beyond the schema. It implies the query parameter is for natural language, consistent with 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 clearly states it's a semantic search in code using OpenAI embeddings, returns file paths, line numbers, and short previews, and explicitly says what it does NOT return (full source). It distinguishes from sibling tools like search_docs and get_file_outline.

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 frames search_code as 'STEP 1 of token-efficient exploration' and provides a concrete workflow: call search_code, then get_file_outline, get_file_folded, get_symbol. It explicitly advises against reading whole files and points to better tools, giving clear when-to-use and when-not-to-use 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 must convey behavior fully. It states the tool returns specific information (file paths, headings, content) and implies read-only operation, but does not explicitly mention read-only, destructive potential, rate limits, or authorization requirements. The description is adequate but not comprehensive.

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 extremely concise, consisting of two sentences that immediately convey the tool's purpose and output. No redundant or irrelevant information is present, making it easy for an AI agent to quickly understand the 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?

Given the tool has only 2 parameters and no output schema or annotations, the description covers the essential aspects: purpose, type of content, and return values. It does not specify defaults (e.g., limit default) or edge cases, but for a search tool this is sufficient.

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 clear parameter descriptions for 'query' and 'limit'. The tool description adds no extra parameter details beyond what the schema provides. Baseline 3 is appropriate as the description does not need to add much, but also does not enhance understanding of parameters.

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 defines the tool as performing semantic search on documentation and markdown files using natural language queries. It specifies the type of content searched and the return fields (file paths, section headings, full content), effectively distinguishing it from sibling tools like search_code and db_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 provides clear context by stating it searches 'documentation and markdown files', implying its use case compared to code or database search tools. However, it lacks explicit when-to-use or when-not-to-use guidance and does not name alternatives, which prevents a higher score.

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 graceful degradation when git or graph are unavailable and specifies the token budget. This provides useful behavioral context beyond what annotations would cover.

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 succinct sentences, each serving a purpose: stating what it is, what it returns, and how it behaves. No unnecessary words, and key information is front-loaded.

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

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

Given the absence of an output schema, the description adequately explains the return content (graph health, cycles, git activity). It also covers edge cases (degradation) and integrates with sibling tools. However, it could specify the format of the blast-radius ranking inclusion.

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?

Though schema coverage is 100%, the description does not add additional meaning to the parameters beyond what the schema provides. 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 clearly states its purpose: a condensed project briefing for the SessionStart hook, listing specific outputs (graph health, cycles, git activity with blast-radius ranking). It distinguishes itself from sibling tools by being a composite summary rather than a specific query.

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 mentions being designed for the SessionStart hook, indicating when to use. It also suggests pairing with another tool for complete priming, giving context. However, it lacks explicit when-not-to-use or alternative tools for similar tasks.

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 present, so description carries full burden. It states 'No API call needed' (offline behavior) and implies read-only by returning a plan. Could be more explicit about non-destructive nature.

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 sentences, front-loaded with purpose, each sentence adds value: purpose, return, usage advice, prerequisite, and behavioral note. No 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?

Given no output schema, the description explains return values clearly. Includes prerequisite and behavioral note. Complete for a two-parameter simulation 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%; both parameters have descriptions with examples. The description adds no new meaning beyond what the schema provides, so 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 clearly states the tool simulates a file move and returns import update plan. It distinguishes from sibling tools like reindex and get_dependencies by specifying its role in migration planning before renames.

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

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

Explicitly says 'Use this before any file rename or refactor' and requires a prior reindex. Provides clear context but does not explicitly 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 provided, so description carries full burden. It discloses 'No API key required' and lists specific thresholds, but does not mention side effects, return format, or behavior when no anomalies exist.

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, well-structured sentence that front-loads the main purpose and then lists thresholds with no superfluous 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 simple list tool with one optional parameter and no output schema, the description adequately covers thresholds and auth requirements. However, it omits scope (e.g., current workspace or all workspaces) and handling of edge cases.

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

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

Schema description coverage is 100% for the single parameter 'period', with enum values and description. The tool description adds no parameter info beyond the schema, meeting the baseline for 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 clearly states the tool lists Claude Code sessions hitting specific health thresholds, with explicit threshold definitions (SES001 cost ≥$25, etc.). It distinguishes itself from sibling tools by focusing on anomaly detection.

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 context but no explicit when-to-use or when-not-to-use guidance relative to siblings. It implies usage for finding anomalous sessions but does not reference alternative tools 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 carries the full burden. It clearly indicates a read-only operation (no side effects) requiring no authentication, and specifies the output content (task categories, MCP counts, tool usage). This is transparent enough for an agent to understand behavioral traits, though more detail on data freshness or potential rate limits could improve it.

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 that immediately states the purpose and lists key output elements. It is front-loaded, concise, and contains no filler or 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?

For a simple informational tool with one optional parameter and no output schema, the description is complete. It explains what the tool returns, lists all relevant categories, and notes the lack of authentication requirements. No additional context is needed.

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 one optional parameter 'period' with enum values and a description. Schema coverage is 100%, so the description adds no additional meaning beyond what the schema provides. 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 clearly states the tool shows token usage breakdown by task category, MCP server calls, and core tool usage. It distinguishes from sibling tools like usage_stats and usage_dashboard by specifying the categorical breakdown and noting 'No API key required,' which differentiates it from other diagnostic tools.

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 for understanding token allocation but does not explicitly state when to use this tool versus alternatives (e.g., usage_stats, usage_dashboard). The mention of 'No API key required' offers a hint but no formal guidance on use cases 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 provided, so description carries full burden. Discloses that it launches a local web server, opens in VS Code Simple Browser, and requires no API key. Lacks details on port collision handling or cleanup, but sufficient for a non-destructive launch 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?

Single sentence of 20 words, front-loads the main purpose, and every phrase adds value. No unnecessary 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?

No output schema exists, but the description explains the user-facing result (interactive charts and dashboard). For a launch action, this is adequately complete; missing details about the server shutdown or refresh behavior would improve but not essential.

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%—the single 'port' parameter is already described in the schema. The description adds no additional context beyond what is in the schema, so 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?

Clearly states verb 'Launch' and resource 'local web dashboard showing Claude Code token usage with interactive charts'. Distinguishes from sibling tools like usage_stats or usage_breakdown which are non-interactive data reports.

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 indicates when to use (to view token usage interactively) and notes 'Opens in VS Code Simple Browser' and 'No API key required'. However, it does not mention when not to use or compare with sibling usage 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 must carry the full burden. It only adds 'No API key required' as a behavioral trait. It does not disclose whether the operation is read-only, idempotent, or has side effects, which is insufficient for a stats 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?

Two concise sentences that front-load the core action. No redundant phrases or unnecessary details.

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

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

The tool has no output schema, yet the description does not describe the return format or fields. Given two simple parameters, this is a moderate gap; a user might need to invoke to understand output.

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

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

Schema coverage is 100% with enum descriptions. The description echoes the grouping options but adds no new meaning beyond the schema, such as explaining what 'cache' or 'anomaly' grouping entails.

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?

Description clearly states the tool retrieves token usage statistics and API costs, with grouping by model/project/day. It distinguishes itself from siblings like usage_anomalies and usage_breakdown by being the general stats endpoint.

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 use for checking consumption, but does not explicitly state when to use this tool versus specific siblings (e.g., usage_anomalies for anomalies). No exclusion criteria or alternatives are mentioned.

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