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

No annotations exist, so the description carries the behavioral disclosure burden. It meaningfully discloses that the tool checks for duplicates and inserts after the last existing import, which are important non-obvious behaviors beyond the basic 'add' operation. It does not mention failure modes or return values, but the main behavioral traits are covered.

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 states the core action and then immediately provides two key behavioral details. There is no filler, repetition, or unnecessary elaboration; every clause contributes useful 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 two-parameter tool with 100% schema coverage and no output schema, the description covers the essential operation and expected insertion behavior. It is slightly incomplete in that it does not address edge cases like files with no existing imports or missing files, but the overall guidance is sufficient for 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?

Schema description coverage is 100%, and both parameters already have clear schema descriptions, including an example for import_statement. The tool description adds no parameter-level meaning beyond what the schema provides, 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 uses a specific action verb ('Add') and names the exact resource ('an import statement to a file'). This clearly distinguishes it from generic siblings like patch_file and from read-only tools like read_file. The primary purpose is immediately understandable.

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 this tool: when an import needs to be added. The duplicate-checking and insertion-position details hint at why it might be preferred over manual patching, but there is no explicit comparison with alternatives like patch_file or insert_after_symbol, and no stated when-not-to-use conditions.

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 disclose behavioral traits itself. It reveals the add/remove/list actions but does not explain whether modifications persist, are reversible, affect source files, or require any authorization. The 'remove' action especially lacks clarity about consequences.

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

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

The description is a single front-loaded sentence that states the action and resource without wasted words. It is easy to scan and parse quickly.

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

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

With no annotations, no output schema, and a mutation-capable tool, the description is too thin. It does not explain what happens after an add/remove, what 'list' returns, or how this metadata is stored or related to project files. An agent would need to guess about side effects and expected outputs.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little meaning by explaining that the categories are business rules, gotchas, and warnings, but it does not provide additional semantics for text, index, or the conditional requirements between parameters beyond what the schema already states.

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 operation ('Add/remove/list') and the resource ('project annotations'), with concrete examples of annotation categories. It is immediately distinguishable from sibling file-reading and editing 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 purpose implies when to use it — whenever an agent needs to manage project-level annotations about business rules, gotchas, or warnings. However, it does not explicitly distinguish this from related editing tools like patch_file or replace_symbol, nor does it 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, the description carries the burden of disclosing behavior. It does disclose that the operation renames across all source files, uses word-boundary matching, and returns modified files and replacement counts. However, it does not warn about side effects like permanent file modifications, collisions, or failure modes, which would matter for a deterministic editing 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 sentences with no filler. The core purpose and scope are front-loaded, and the return value is stated briefly in the second sentence. Every word contributes useful 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?

The tool has three parameters, all documented in the schema, and the description covers the operation's scope, matching behavior, and return value. Although there is no output schema, the return format is explicitly summarized. Minor gaps remain around whether files are written immediately and how conflicts are handled, but the description is fairly complete for a rename 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%, so the schema already documents all three parameters. The description adds a little semantic nuance with 'word-boundary match' for old_name, but it does not meaningfully elaborate on new_name or file_pattern beyond what the schema already states.

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

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

The description names the action (rename), the subject (a symbol), the matching rule (word-boundary match), and the scope (all source files in the project). This clearly distinguishes it from narrower editing tools like replace_symbol or patch_file, since it signals a project-wide operation.

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 that this tool is for renaming a symbol project-wide, which gives clear context for when it would be appropriate. However, it does not explicitly state when to prefer an alternative (e.g., replace_symbol for a single occurrence) or mention any exclusions or prerequisites.

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

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

With no annotations, the description must carry the behavioral disclosure burden. It discloses that the tool regenerates docs and is normally automatic, but it does not state whether the operation is destructive, what files are touched beyond '.reposynapse/', whether it can be safely rerun, or what it returns.

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

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

Two short sentences each carry useful information: the action/resource and the automaticity caveat. There is no filler, and the key action is front-loaded.

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

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

For a zero-parameter tool with no output schema, the description is nearly sufficient: it names the target and gives an important usage caveat. It could be slightly more explicit about the effect of calling it manually, but nothing critical is missing for an agent to invoke it.

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

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

The schema has zero parameters and 100% coverage vacuously, so there is no parameter semantics burden on the description. The baseline of 4 applies because there are no parameters whose meaning needs explanation.

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

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

The description names a specific verb ('Regenerate') and a specific resource ('.reposynapse/ docs'), so an agent can tell this is a documentation-generation action. It doesn't explicitly differentiate from siblings like 'annotate' or 'get_project_context', but the resource target makes the purpose reasonably clear.

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?

'Usually automatic' implies the agent should only call this when automatic regeneration hasn't happened, giving some usage context. However, it stops short of stating explicit when-to-use or when-not-to-use conditions or naming alternatives, so guidance is mostly implied.

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 of behavioral disclosure. It reveals 'ultra-compact output' as a return trait and implies a read-only scan, but it does not explain whether thresholds combine, how results are ordered, or what specific fields are returned.

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

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

Two sentences with no filler. The core function is stated first, followed by the purpose and output trait. 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?

For a tool with three optional, fully documented parameters and no output schema, the description provides enough context to invoke correctly: what it lists, why to use it, and what the output is like. It could detail the output format, but that is not essential for a simple analysis 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%, and each parameter already has a clear description with defaults and an example for file_pattern. The description adds no significant meaning beyond 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?

The description uses a specific verb ('List') and resource ('functions/methods') with a clear criterion ('above complexity thresholds... too many lines or params'). This clearly distinguishes it from sibling tools like read_file or search_in_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?

The phrase 'to help prioritize what to refactor without reading every file' provides a clear use case and context. It doesn't explicitly name alternatives or exclusion conditions, but the intended scenario is evident.

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 significant behavior: it returns only fatal errors, filters out spelling errors and warnings, auto-detects the language, and runs the appropriate checker. It does not mention output formatting or non-mutation explicitly, but the diagnostics framing makes the lack of side effects reasonably 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 long, front-loads the key scope ('fatal errors'), and every clause adds value—language support, auto-detection, and token-saving filtering. There is no redundant or filler 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 zero-parameter tool with no output schema, the description covers the essential context: what it runs, on which languages, and what it returns. It could mention the form of the error output or that this is a read-only operation, but the current content is sufficient for an agent to invoke it correctly.

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

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

This tool has zero parameters, triggering the baseline of 4. The description adds relevant context by explaining why no parameters are needed: the language is auto-detected and the appropriate checker is run automatically.

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 ('Run project diagnostics') and a clear resource, plus the return scope ('ONLY fatal errors'). It is distinct from sibling tools like get_complexity or search_in_project, so an agent can select it without opening the schema.

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

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

The description provides clear usage context: use this to get fatal diagnostics across multiple supported languages, with auto-detection. It does not explicitly mention alternatives or exclusions, but with no parameterized inputs and a clear purpose, the intended usage is well implied.

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 description carries burden. It reveals default behavior ('compact' format) and hints at re-analysis with force_refresh. It doesn't disclose potential side effects, cost, or performance implications of force_refresh or calling FIRST. 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?

Two short sentences, front-loaded with the most important instruction. Every word earns its place; no wasted text.

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

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

For a tool with 3 optional params and no output schema, the description is reasonably complete for routing, but it doesn't describe the returned context structure or what 'specific info' means beyond sections. Lacks nuance about format param or force_refresh semantics. Given the tool's complexity (enum-heavy, many sections), it's adequate but leaves the agent to infer some behavior.

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

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

Schema coverage is 100%, with detailed parameter descriptions in the schema itself (e.g., section values and default). The description adds the 'modified' value meaning and 'Call FIRST' guidance, which is marginal. Baseline 3 is appropriate since schema already documents 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 states a specific verb ('Call FIRST', 'Returns project context') and resource, clearly distinguishing this as the primary project-context tool. It doesn't explicitly name siblings but the guidance is sufficient to differentiate it from file/search operations.

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 usage directive: 'Call FIRST' and 'Use section param for specific info.' It implies this is the entry point before other tools, though it doesn't explicitly state when not to use it or name alternatives. The sequential guidance adds practical 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It states the insertion action but omits important behavior such as what happens if the symbol is missing, how duplicate symbols are handled, whether indentation is adjusted, or what the tool returns after a successful insertion.

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 short sentences with the primary action front-loaded and a useful example use case following it. Every sentence earns its place; there is no filler or 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?

For a simple mutation tool, it covers the basic operation and typical use case, and the schema covers all parameters. However, it lacks guidance on error behavior, formatting/indentation expectations, and explicit alternatives, and there is no output schema to clarify return values.

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 all three parameters are already documented in the schema. The description adds context around 'symbol' as a named function/class and typical use for methods/helpers, but it does not add meaningful details about the code parameter format or file path resolution.

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 ('Insert code') and the target ('after a named function or class'), so an agent knows what the tool does. It does not explicitly differentiate from siblings like patch_file or replace_symbol, but the placement detail makes the purpose reasonably distinct.

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 concrete use case: 'adding a new method or helper next to a related one.' However, it does not explain when to prefer this over alternatives like patch_file or replace_symbol, nor does it mention any exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. 'Respects .gitignore' is genuinely useful context that prevents confusion when ignored files are absent from results. However, other behaviors — recursion semantics, handling of hidden files, path formatting in output — are not disclosed.

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

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

Two short sentences with zero wasted words: the first states the purpose, the second adds a meaningful behavioral caveat. Information is front-loaded and every word earns its place, which is exactly right for a simple listing 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?

The tool is moderately complex (three optional parameters that alter behavior) with no annotations and no output schema. The description does not explain the return shape, whether traversal is recursive, or how max_depth interacts with the listing, so an agent must discover these details by calling 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 description coverage is 100%, with clear descriptions for path, pattern, and max_depth already present in the schema. The tool description adds no parameter-level meaning, so the baseline 3 applies; the schema does the heavy lifting 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 states a specific verb and resource — 'List files/dirs' — which is unambiguous and clearly distinct from sibling operations like read_file, search_in_file, and patch_file. It doesn't explicitly name a sibling it is not, but the purpose is self-evident and easy for an agent to act on.

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

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

There is no guidance on when to use this tool versus alternatives such as search_in_project or read_file. The description provides no context about prerequisites, exclusions, or when listing is the right first step, leaving the agent to infer usage solely from the tool's name.

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

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

With no annotations provided, the description must disclose behavioral traits on its own. It only says the tool applies a diff patch; it does not mention failure behavior, whether changes are reversible, what happens on a non-applicable patch, or any side effects. This is a notable gap for a file-mutating 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 sentences: the first front-loads the action, the second explains the practical benefit. No wasted words, and information is easy to parse.

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 mutation tool with no annotations and no output schema, the description covers the core operation but omits failure modes, return values, and edge-case behavior. It is adequate for a basic understanding but leaves important gaps for an agent deciding on reliable invocation.

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

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

Schema coverage is 100%, with clear descriptions for both 'file' and 'patch'. The description does not add additional parameter-level semantics beyond noting that only changed lines are sent, 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 clearly states a specific verb and resource: 'Apply a unified diff patch to a file.' It also differentiates itself from full-file write approaches by explaining the token-saving advantage, which helps an agent understand its distinctive role among the 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 token-saving rationale implies this tool is for large files where sending the full file would be wasteful, but it does not explicitly name alternatives like replace_symbol or insert_after_symbol or state when not to use it. Usage context is present, but exclusions and explicit routing are missing.

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

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

With no annotations, the description carries the behavioral burden and it does reveal the key adaptive threshold of 200 lines, which is genuinely useful. However, it does not disclose what an outline contains, how errors are handled, whether reads are read-only beyond the 'reader' framing, or any limits on the line range.

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 entire description is one front-loaded label plus three short clauses, with no filler. It is tightly structured so an agent can scan the threshold and optional-range behavior immediately.

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 tool with no annotations and no output schema, the description covers the core usage and adaptive behavior, which is a minimum viable definition. It leaves gaps around the outline format, line-range inclusivity, and sibling selection, so it is not complete enough for nuanced choices.

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 all four parameters with 100% coverage, so the baseline is 3; the description adds that the line range is optional and relates it to the content/outline threshold. This is helpful but does not substantially deepen the meaning of start_line and end_line 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 identifies this as a smart reader for files and specifies the adaptive behavior (<200 lines returns full content, >200 lines returns an outline) and optional line-range support. It is distinct from the generic name, but it does not explicitly distinguish itself from the read_file_outline sibling, and 'outline' is left undefined.

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 reading a file, with an optional line range to narrow the read, and describes automatic behavior by file size. It does not, however, state when to choose read_file over read_file_outline or search_in_file, despite several closely related siblings.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It usefully discloses the output shape (symbols with line ranges) and token consumption behavior for different depth values, which helps the agent anticipate cost. However, it does not mention error handling, path resolution behavior, or the absence of full file content, leaving some behavioral aspects implicit.

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

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

The description is two concise sentences that front-load the core purpose and immediately give actionable token estimates. Every phrase adds value and there is no redundancy or filler.

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

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

For a lightweight outline tool with no output schema, the description adequately conveys the return value and how to control verbosity with depth. It does not explicitly note that a file path is effectively required despite the schema marking no required fields, and edge-case behavior is omitted, but these are minor for this simple 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%, so the schema already documents file, depth, and file_path. The description repeats the token-saving rationale already present in the depth schema and adds no new parameter-specific meaning. The baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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 that the tool returns a file outline consisting of symbols with line ranges, which is a specific and actionable purpose. It is implicitly distinguishable from siblings like read_file and read_file_symbol, though it does not explicitly name them.

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 parameter-level guidance (use depth=1 for top-level only) but no explicit advice on when to choose this tool over siblings such as read_file or read_file_symbol. It leaves tool-selection decisions to inference rather than stating when or when not to use this tool.

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 does communicate that the operation is a read and that fuzzy matching is supported, but it does not disclose what happens with multiple fuzzy matches, whether the whole symbol body is returned, or any other side effects or limits.

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

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

Two short sentences, front-loaded with the core action and resource. Every word earns its place, and the fuzzy-matching note is a useful second sentence rather than padding.

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

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

The tool has no output schema and no annotations, so the description must explain more than it does. It omits what is returned when a match is found, how ambiguity is resolved, and what happens when the optional file parameter is omitted—significant gaps for an agent trying to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the symbol parameter refers to a function/class name and that fuzzy/partial names are accepted, which goes beyond the schema's generic 'Symbol name' description. It does not address the file/file_path alias semantics, but those are already documented 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 states a specific verb (Read), a specific resource (function/class), and the lookup mechanism (by name), which clearly distinguishes it from siblings like read_file (whole file) and read_file_outline. Fuzzy matching is an extra scoping detail that further clarifies what kind of matches are returned.

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

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

There is no explicit when-to-use statement or named alternatives. The phrase 'by name' and 'Fuzzy matching supported' imply the agent should use this when it already has a symbol name (possibly approximate) rather than when it needs to explore a file, but this is left to inference.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently states that the default is non-destructive reporting and that dry_run=false deletes the symbols. It could add details about permanence or file modification scope, but it clearly signals the destructive path.

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 purpose and then clearly states the safety/default behavior and the destructive alternative. 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 tool with two simple, fully documented parameters and no output schema, the description is largely complete: it explains what the tool finds, what it reports by default, and what happens with dry_run=false. It could mention the output format or irreversible side effects, but the core invocation context is present.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the dry_run semantics but adds no extra meaning beyond the schema, and it does not elaborate on file_pattern behavior.

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

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

The description states a specific verb and resource: find exported symbols never imported by other files, with an optional delete action. This clearly differentiates it from sibling tools like search_symbol or read_file_symbol, which locate/read symbols but do not analyze dead code or delete 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 gives clear context: use it to find dead exports, with dry_run=true as the safe default and dry_run=false triggering deletion. It doesn't explicitly name alternatives or exclusions, but the intended usage is unambiguous enough for an agent to select it appropriately.

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 disclosure burden. It communicates that the operation mutates by replacing an entire symbol body and that only the new implementation is required, which is useful behavioral context. However, it does not mention what happens if the symbol is not found, whether the operation is reversible, or what it returns.

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 efficient sentences: the first states the action and target, the second adds a genuinely useful workflow note. There is no filler or repetition of schema 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 three-required-parameter write tool with full schema coverage and no output schema, the description covers what is replaced, what the AI must supply, and the fact that pre-reading the file is unnecessary. Minor gaps remain around failure behavior and explicit sibling-tool routing, but the core selection and invocation information is present.

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

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

Schema description coverage is 100%, so the parameter meanings are already documented. The description reinforces that new_body is the only implementation payload, but it adds no semantic detail beyond the schema, 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 names a specific action ('Replace') and resource ('the full body of a named function, class, or interface'). The 'full body' qualifier distinguishes it from partial-edit tools like patch_file and insert_after_symbol even without naming them.

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 indicates the intended case for whole-symbol replacement and gives a practical workflow cue ('no need to read the full file first'). It does not explicitly describe when to prefer a sibling tool or when not to use this tool, so it stops short of full 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 behavioral burden, but it only discloses regex support, which is already implied by the schema's 'string/regex' parameter description. It does not mention return value format, pagination, or behaviors like line numbers or file path handling.

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

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

The description is extremely concise, front-loaded, and contains no filler. However, it is so minimal that it omits useful context, making it efficient but slightly under-specified for a tool with no annotations.

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

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

For a tool with no annotations and no output schema, the description is too sparse. It does not explain what the search result looks like, how to interpret matches, or how this tool relates to the many search-related siblings. An agent would need to inspect the schema extensively to use it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds no additional parameter-level meaning beyond what the schema already provides, 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 a specific verb and resource: 'Search pattern in file', and notes regex support. It is clear and distinguishes itself from project-level search tools in scope, though it does not name sibling alternatives.

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 does not say when to use this tool versus alternatives like search_in_project or search_symbol. The file-scoped behavior is implied but no explicit when-to-use or when-not-to-use guidance is given.

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

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

With no annotations, the description carries the behavioral burden. It discloses the default compact output format, total matches, file count, top 10 hottest files, code detail behavior, and grouped/sorted output mode. It does not mention performance characteristics, but the disclosed default and mode behaviors are substantial and meaningful.

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 tight sentences with no filler. The most important fact (search scope) comes first, followed by defaults and mode-specific usage. Every clause earns its place and front-loads the default behavior before the optional modes.

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 search tool with six parameters and no output schema, the description covers the essential return behavior (compact summary, code detail, grouped files) and calls out the key mode switch. Parameter-level details like max_results, context_lines, and exclude_pattern are already fully documented in the schema, so nothing critical is left unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the compact summary output, the top-files behavior, and how max_files=-1 changes the output into a grep-like grouped listing. This is real semantic enrichment rather than repetition.

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

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

The description states a clear verb and resource: 'Search across all project files.' It also specifies the output modes ('1-line compact output', 'code detail', grouped/sorted file list), which distinguishes this from sibling tools like search_in_file and search_symbol by emphasizing project-wide scope.

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 instructions for when to use each mode: max_files=N for code detail, and max_files=-1 with file_pattern as a grep replacement. It does not explicitly contrast with sibling tools or state when not to use them, but the 'across all project files' scope and grep-replacement framing provide clear contextual usage 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 behavioral disclosure burden. It discloses read-only behavior implicitly, describes returned data, supports fuzzy/regex matching, and explains the context_lines preview feature. It does not mention result limits, ordering, or match-count behavior, but overall provides strong transparency for a search 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 compact, front-loaded with the core purpose, and every sentence adds value. It includes useful examples without unnecessary fluff, and the filter guidance is clear and actionable.

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 six parameters, a nested object, and no output schema, the description covers all major behavior and gives practical filter examples. It mentions return fields and preview behavior, though it omits result ordering, limits, and exact matching semantics. These are minor gaps for a search 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%, so the baseline is 3. The description adds value by giving concrete usage examples for name, path_filter, and context_filter, and explaining how to use context_lines for previewing code. The extra examples and use-case guidance justify a 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 searches for symbols across project files and lists the return values (file location, type, signature, exported status). It distinguishes itself from text-search tools by focusing on symbols rather than file content, but does not explicitly name or contrast 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 gives concrete usage guidance with regex examples and explains when to use path_filter and context_filter to narrow results. It does not explicitly describe when to prefer this tool over siblings like search_in_project or search_in_file, but the intended use case is clear.

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