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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond that: it reads files only, replaces the previous scan, and can take a few seconds on a large project.

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

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

The description is front-loaded with the action and purpose, then covers usage, return shape, and side effects without filler. Every sentence adds useful information for invoking or interpreting 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?

There is no output schema, but the description explicitly lists the return shape and notes that duplications are biggest first. For a two-parameter scan tool with annotations covering safety, the description is complete enough to call and interpret correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail, including the kinds enum and limit behavior. The description does not add parameter-specific semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: scanning the paths the server was started with and returning a fresh clone list and counts. It also distinguishes itself by tying its duplication output to get_file_clones and by explaining that other tools should answer from current content after a scan.

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 after creating, editing, or deleting files so other tools answer from current content. It does not state when not to use it, which keeps it below a full 5, but the usage context is clear.

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

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

Annotations only cover the safe-read profile; the description adds substantial behavior: results are ordered exact → renamed → similar → semantic, a --min-tokens threshold (50 default) prevents short snippets from matching, unfindable kinds appear under 'unavailable', semantic search runs an embedding model that is slow the first time, and renamed/similar may need an extra scan. It also documents the legacy no-'kinds' response shape, which is real behavioral variance.

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

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

Purpose and usage are front-loaded in the first sentence, and the dense return-format detail is justified because no output schema exists. It does read as one long wall of text bundling edge cases (Markdown/Vue/Svelte/Astro splitting, threshold notes) that could be sectioned, but little is truly wasted.

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 output schema, the description takes on the full burden and delivers: it enumerates every returned field, explains the 'lines' vs match-span distinction, and covers degraded responses ('note', 'unavailable'). An agent has everything needed to call this and interpret the result.

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 carries most parameter meaning. The description still adds cross-parameter semantics the schema does not: supplying 'similarity' implicitly requests ast matches, and omitting 'kinds' changes how ast results are reported ('similar' with 'similarCount'), plus the note that ast matching only covers a listed set of languages.

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

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

States a specific verb and resource ('Check whether a code snippet duplicates code that already exists in the scanned project') and scopes it to the last scan. It is clearly distinguishable from siblings like get_file_clones (project-wide listing) and compare_folders (folder-to-folder).

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

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

Gives an explicit trigger ('Use it before writing or committing a function, class or block, to find the existing code you should reuse instead') and an explicit prerequisite/alternative: 'call check_current_directory first if files changed'. Both when-to-use and when-to-refresh are covered.

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?

Beyond the readOnly/idempotent annotations, the description discloses the operational cost ('needs the embedding model', 'the first comparison ... can take minutes, later ones reuse the cached vectors') and describes the full returned report. It also flags correctness risk by warning that name-matched and low-level pairs should be spot-checked, which the annotations cannot convey.

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?

It is front-loaded with purpose and argument ordering and every sentence carries information. The long parenthetical enumeration of returned sections is dense but justified because no output schema exists, though it could be tightened.

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 output schema, the description fully carries the return-value burden: it names the 'code'/'tests' sections, the per-side fields including 'readyToPort', and the 'pairs' fields including 'similarity', 'level', 'renamed' and 'matchedBy'. Combined with model requirements and caching behavior, an agent has what it needs to call this 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 already 100%, so the baseline is 3, but the description adds the semantic ordering rule (left is the source, right the target) and implies the left/right containment constraint the schema also states. The 'limit' parameter's truncation behavior is left entirely to the schema, so it isn't a full 5.

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

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

The description gives a specific verb and resource — compare two folders function by function — and immediately names the two scenarios it serves (a port and its original, or two implementations of one app such as iOS and Android). That is enough to distinguish it from the sibling tools get_statistics, check_duplication and get_file_clones, which operate on duplication statistics or clone lists rather than cross-folder function pairing.

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 spells out both intended scenarios and the argument ordering (source first, target second), and it adds a concrete interpretation rule: read a few low-similarity pairs and the pairs matched by name before relying on them. It never explicitly states when not to use it or names a sibling as the alternative for plain clone or duplication queries, so a 4 rather than a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description goes beyond them: it discloses the ordering (biggest first), the edge case where an unscanned path returns 0 clones plus a 'note', and the cost/latency caveats for semantic clones and extra scans.

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

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

Purpose, usage, and return shape are front-loaded in that order with no filler sentences. The long enumeration of return fields is dense but earns its place given there is no output schema.

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

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

With no output schema, the description fully compensates by specifying the response envelope, per-clone fields, ordering, and the not-found shape. An agent has everything needed to call and interpret 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?

Schema coverage is 100%, so baseline is 3; the description adds meaning by explaining that results may place the requested file as either fileA or fileB, and by describing the unscanned-path outcome that affects the 'path' parameter. It does not elaborate on kinds/limit beyond the schema, so not a 5.

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

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

Specific verb and resource — 'List every clone of the last scan that involves one file' — plus a scoping phrase ('which other files share code with it') that separates it from siblings like check_duplication and get_statistics.

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

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

Gives a concrete usage context ('before refactoring, splitting or deleting a file'), which is clear guidance on when to reach for it. It does not name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses important snapshot semantics: it reflects the last scan, not the files currently on disk. It also enumerates the reported statistics, including the 'byKind' breakdown. It does not cover cost or timing details, though those appear in the parameter schema.

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

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

The description is front-loaded with the core purpose and the key caveat about the last scan. The first sentence is dense and long, but each part carries useful information and the later sentences add workflow guidance 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?

With no output schema, the description does a good job listing the returned statistics and explaining the stale-scan behavior. It omits precise output shape details, but gives enough for an agent to understand what the call yields and when to use 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?

Schema description coverage is 100% and the sole 'kinds' parameter is fully documented in the schema, including defaults, enum meanings, and performance notes. The description only alludes to 'the clones of the kinds asked' and does not add meaning beyond the schema.

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

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

The description states a specific verb and resource ('Report the duplication statistics of the last scan') and clarifies the aggregate scope ('whole project and per format'), which helps distinguish it from per-file tools like get_file_clones. It does not explicitly contrast with check_duplication, so sibling differentiation is good but not complete.

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

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

It gives clear usage contexts: judging overall duplication and comparing before/after a refactoring, with the concrete instruction to call check_current_directory in between. It does not state when not to use it or name get_file_clones as the alternative for per-file clone data.

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