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

With no annotations, the description carries the full burden and meets it: it discloses the false-positive exclusions, the unresolved definition-binding limitation and that the answer explicitly says so, the different behavior for file inputs, and reliance on the same statically resolved import graph as `used by`.

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

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

The core semantics are front-loaded and every clause adds information, including the shell invocation and PATH fallback. It is long and somewhat dense, but it is not padded.

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 having no output schema and no annotations, the description conveys the substance of results: definition(s) first, enclosing function, path:line, and the unresolved-binding caveat. The main gap is the undocumented optional parameters `ref` and `output_format`.

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 description adds meaning for `name` (function/method or file) and `directory` via `--dir`, which is valuable given zero schema description coverage. However, it never explains `ref` or `output_format`, so an agent cannot know what `ref` refers to or which output formats are valid.

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 specific operation: producing actual call sites of a function or method across a directory. It sharply excludes false matches like prose, comments, docstrings, and string literals, and also explains the file-input mode for finding importers.

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 usage context: a qualified name narrows definitions, a file input switches the tool to importer discovery, and `--dir` controls the directory scope. It does not explicitly name when-not-to-use sibling tools, but the invocation guidance is concrete and actionable.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses that results are review hints, not verified bugs, and explains the meaning of a silent result. It does not mention side effects, permissions, or failure behavior, but the read-only audit nature is strongly implied.

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

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

The description is compact and front-loads the core concept before the caveat and shell usage. The shell command sentence is arguably extra but still useful and does not bloat the description significantly.

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

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

The tool's purpose, caveats, and silent-result behavior are covered, but there is no output schema and the description does not explain the structure of the findings. It says 'findings' are capped, but an agent would still wonder what a finding includes or how it is formatted.

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?

All three parameters are fully described in the input schema (100% coverage), so the description does not need to add parameter-level details. The shell command in the description is useful context but does not enhance parameter understanding.

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 purpose with a concrete example of peer divergence ('peers calling X also call Y, this one does not') and immediately qualifies it as a review hint. It does not explicitly differentiate itself from sibling tools like scan_directory or callers, so it misses the top score.

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 this is a heuristic review tool rather than a definitive bug detector, and notes that silence on a consistent codebase is meaningful. However, it does not explicitly say when to choose this over sibling tools 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, the description carries the full burden, and it reveals important behavior: rename detection by identical body, following file moves, counting but not listing unrelated commits, and identifying the introducing commit. This is strong, though output details remain only loosely indicated via the git log -L comparison.

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?

Every sentence carries substantive information and there is no filler. However, the opening sentence is convoluted and passive, burying the basic 'what this tool does' under tracking details before a cleaner analogy appears.

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 gives rich behavioral rules and concrete invocation examples, but there is no output schema and the return format is only approximated by the git log -L analogy. Behavior around output_format and repo is not explained, leaving meaningful gaps for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains location via examples (`path::name` or `path:line`) and shows ref usage with `--ref REF`, but repo and output_format are not described at all. Core parameters are covered, ancillary ones are not.

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 behavior: follow a code structure backwards through commits, including renames and the introducing commit. The git log -L analogy reinforces the purpose. It is somewhat dense and jargon-heavy, but still distinguishes this from 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 description implies when to use the tool: when you need history of a structure rather than a plain file or directory. It gives concrete shell invocations, but it does not explicitly compare against siblings or state when not to use it.

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

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

With no annotations, the description carries the burden, and it does disclose key behavior: returned output is a tree of one-line gists, elided content is marked '⟨…⟩ +N', and depth choices have token budgets. It does not cover side effects, auth, or error behavior, but for a read-only listing tool this is reasonably 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?

The text is dense and disorganized, burying the core 'folders only' behavior mid-way and appending shell-specific fallback instructions ('sct --help', venv python path) that are not relevant to MCP invocation. The opening sentence is vague and does not front-load the tool's main purpose.

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

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

It covers the main output shape (directory tree, one-line gists) and depth-related behavior, which is useful since there is no output schema. But without parameter documentation for max_depth and respect_gitignore, and without clarifying the first-sentence ambiguity, an agent cannot reliably invoke all parameters 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 0%, so the description must explain the parameters, but it only hints at directory and refers to '--depth quick/normal/deep', which does not map cleanly to the max_depth integer parameter and could mislead an agent into passing those strings. respect_gitignore is not mentioned at all.

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 the resource as directory hierarchy ('Folders only, no files: the directory hierarchy') and the result as a tree with one-line gists, which is more specific than merely restating the tool name. However, the opening 'Skeleton of files or a directory' blurs whether files are included, and no sibling is named, so it is not a perfect differentiator.

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

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

It gives a clear scope ('Folders only, no files') that tells an agent when this directory-tree tool is appropriate and when it is not, and it explains depth-mode trade-offs in token budgets. It does not explicitly name sibling alternatives like scan_directory or preview_directory, so it stops short of a 5.

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

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

No annotations exist, so the description bears full behavioral burden, and it delivers: it explains output parts, line counts, --part behavior, the merge-order hint not being a verdict, and the nuanced meaning of patch-equivalence. It also clarifies what can and cannot be concluded from branch-in-base criteria.

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 dense, but each clause carries meaningful information: output parts, inclusion criteria, part filtering, merge-order caveat, and invocation. The structure is front-loaded with the core analysis semantics and ends with practical command details, though the long sentences require careful parsing.

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?

In the absence of an output schema, the description thoroughly explains the return structure and semantics. It covers invocation and core required parameters, but leaves some optional parameters undocumented; this is a gap, not a fatal one, since base and branches suffice for the main use case.

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

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

With 0% schema coverage, the description compensates for base, branches, and part by explaining base/merge-base semantics and the --part ID behavior. However, kind, path, repo, and output_format are left undefined, making the parameter documentation incomplete for a tool with seven 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 analytical task: comparing N branches against one base at each branch's own merge-base. It enumerates the distinct outputs (touched structures, independently introduced names, shared commits, branch inclusion criteria), clearly distinguishing it as an overlap-analysis tool rather than a generic diff or history tool.

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 shell invocation and the phrase 'N branches against one base' imply when to use this tool, but there is no explicit guidance about when to prefer it over siblings like find_divergence or history. It tells the agent how to run it, but not the conditions that should trigger selection of overlap over 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 are provided, so the description must disclose behavior. It mentions the output size (3-5k tokens) and content (parts, line counts, form to fetch one part). However, it does not explicitly state whether the operation is read-only, has side effects, or requires specific permissions. It does give a shell command, which is helpful, but the behavior beyond the output is not fully disclosed.

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

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

The description is verbose and poorly structured. The first sentence is cryptic ('No command on a directory = orientation'), and the information is scattered. It includes a shell command but does not front-load the tool's purpose. It is not 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 the tool has 6 parameters, no schema coverage, no output schema, and no annotations, the description is severely incomplete. It does not explain how parameters affect the output, what the exact return format is, or how to use the tool beyond a shell command. An agent cannot reliably use this tool based on the description.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It does not. The only hint is 'the form that fetches one part alone', which might refer to the 'part' parameter, but it is not explicit. Parameters like depth, max_files, max_entries, respect_gitignore are completely unmentioned.

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 is cryptic and vague. It mentions 'orientation' and lists content like size, language mix, entry points, hot functions, and call-graph map, but does not clearly state that this tool provides an overview of a directory. The phrasing 'No command on a directory = orientation' is confusing and does not clearly differentiate from siblings like scan_directory or list_directories.

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: 'for first-time orientation of an unknown codebase, not for targeted questions'. It also indicates that for a file tree, one should use 'scan' (likely a sibling), providing clear context and an exclusion. However, it does not name specific sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining the outcome categories (same place, renamed with identical body, gone with nearest names) and the structure of the result. It does not mention whether the operation is read-only or describe edge-case handling, but the core behavior is clearly disclosed.

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

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

The description is compact and front-loaded: the core definition appears first, followed by concrete invocation examples. No sentence is wasted, though the density of the first sentence might make it slightly harder to 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?

For a tool with no annotations and no output schema, the description covers the main operation and gives usable syntax examples. It is incomplete regarding the repo parameter, output_format values, and exact return shape, which an agent would need for robust 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 description coverage is 0%, so the description must compensate. It adds useful meaning for location (path:line or path::name), ref_from (--from REF), and ref_to (--to REF). However, it does not explain repo or output_format at all, leaving two of the five parameters with only their names and defaults as guidance.

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 verb ('Translate') and resource (path:line or path::name across refs), and specifies the exact operation: locating the enclosing structure at --from and its counterpart at --to. This distinguishes it from the sibling scanning/searching tools, which focus on listing or diffing content rather than ref-to-ref translation.

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

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

Usage is implied through concrete shell examples showing both the path:line and path::name forms. However, there is no explicit statement of when to prefer this tool over siblings like find_divergence or surface, nor 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 carries the full burden of behavioral disclosure, and it is remarkably transparent. It discloses merge-base vs tip comparison, the per-file symbol legend, folding of identical deltas, skeleton files, coverage-line behavior, and the review tail with dead/orphan/drift candidates. It even notes that --review is off by default and that a note indicates which comparison mode was used.

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 dense and front-loaded, starting with the core purpose and then providing the output legend and shell usage. It earns its length for a complex tool, but there is some redundancy, such as repeating 'ref vs the working tree, or ref vs ref2' and 'review=True appends the review tail.' It is slightly over-packed but still well structured.

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

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

For a complex 7-parameter tool with no annotations and no output schema, the description covers the diff semantics and output rows very well. Yet it omits three parameters, including the only required one, directory, plus budget and output_format, leaving an agent with gaps for a correct invocation. The detail elsewhere makes these omissions conspicuous.

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?

Because schema description coverage is 0%, the description must supply parameter meaning, and it does for ref, ref2, no_merge_base, and review. However, budget, directory (the only required parameter), and output_format are never mentioned, so an agent cannot determine their semantics from either the schema or the description. This is a meaningful gap.

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

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

The description opens with 'Structural diff between refs,' naming a specific verb and resource, and then explains one-ref vs two-ref semantics precisely. The detailed output legend makes the purpose unmistakable. It does not explicitly differentiate from sibling tools, so it misses the full 5, but the purpose is otherwise very 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?

The description explicitly says 'Use instead of git diff for review and "what changed" questions,' providing both a use case and an alternative. It also explains when to use one ref vs two refs and how the default merge-base behavior works. It does not enumerate sibling-tool exclusions, but the guidance is strong enough for correct selection.

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

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

With no annotations, the description carries the full disclosure burden. It is transparent about key output behaviors: depth-specific token budgets (~300/1500/whole), elision markers (⟨…⟩ +N), one-line gists, code health/churn labels, and reading a specific git ref. It stops short of stating that the operation is read-only, but the core output behavior is well 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 dense but unstructured, mixing output format, depth rules, elision markers, and a shell command in one unparagraphed block. It repeats the directory-tree statement twice ('A directory gives the tree with one-line gists' vs 'A directory: the file tree with one-line gists per file...'). The shell snippet is useful but tangential, and the prose could be tightened into clearer sections.

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 12 parameters, no output schema, and no annotations, the description is under-specified. It explains skeleton/tree output and covers `depth` and `ref`, but an agent cannot determine the semantics of `mode`, `delta`, or `caller`, or the allowed values of `output_format`. The lack of return-format guidance beyond the elision markers makes it hard to parse results reliably.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `depth` and `ref`, and indirectly hints at `include_metadata` via 'code health and churn labels.' However, it leaves `mode`, `delta`, `caller`, `max_files`, `output_format`, `exclude_patterns`, `respect_gitignore`, and `pattern` unexplained; opaque params like `delta` and `caller` remain ambiguous. The description does not carry the weight needed for this low-coverage 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 what the tool produces: a structure skeleton with path:line, signature/title, and condensed excerpt, plus a directory tree with one-line gists and metadata labels. It also differentiates itself by claiming to replace Glob/ls for all file types. However, it never explicitly names sibling tools like list_directories or preview_directory, so differentiation relies on inference.

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

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

The description gives a clear context of use: it replaces Glob/ls for all file types, signaling when an agent should reach for this rather than a simple listing. It also offers depth-mode and ref options as practical usage hints. Yet it provides no explicit 'when not to use' guidance or direct comparison to sibling tools such as scan_file_content or preview_directory.

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 does a substantial job: it discloses output shape, token budgets per depth, elision marker semantics, focus/body_only behavior, and the optional CONNECTIVITY note. It leaves some behaviors like mode/delta/condense/output_format unexplained, but the core scanning behavior is well disclosed.

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

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

The description packs a lot of useful information but does so as one dense run-on paragraph with semicolons. It front-loads the main purpose, yet the lack of structure makes the many details harder to parse; every sentence is informative, but the format is not optimized for an agent scanning the text.

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

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

For the required file_path and the main optional parameters, the tool is well specified with budgets, focus semantics, ref handling, and elision behavior. However, with 16 parameters, zero schema descriptions, and no output schema, the many unmentioned toggles leave the definition incomplete for full correct invocation across all options.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for file_path, depth, budget, focus, body_only, and ref, but 16 parameters exist and most are never explained: mode, delta, condense, caller, output_format, show_complexity, show_decorators, show_docstrings, show_signatures, and include_metadata are all absent from the 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 what the tool does: it produces a skeleton of a file or directory with path:line, signatures/titles, and budgeted excerpts. It is concrete about the resource and result, but it does not explicitly differentiate itself from sibling tools like scan_file_content or scan_directory, even though it also handles directories despite the 'file' name.

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 practical guidance: budget=1500 for exploration, 300 for a quick look, focus for reading a single node, body_only to suppress the outline, and ref for git refs. However, it does not name alternatives or exclusion conditions, so an agent has to infer when scan_file_content or scan_directory would be more appropriate.

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 budget behavior (quick ~300 tokens, normal 1500, deep everything), elision marking (⟨…⟩ +N), focus behavior, and the fact that content can be piped via stdin. It also explains the CLI invocation fallback. This is substantial behavioral context beyond the schema. However, it doesn't disclose side effects (likely none) or error conditions, and the 'same budget/depth and focus as scan_file' reference assumes knowledge of another 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 dense and information-rich, but it's a single run-on paragraph that mixes conceptual explanation with CLI usage examples. The most important distinction (content given directly) appears mid-paragraph rather than front-loaded. The CLI invocation details are useful but could be separated or condensed. Every sentence earns its place, but the structure could be improved.

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 14 parameters, no annotations, and no output schema, the description is incomplete. It explains the core scanning behavior and budget/depth semantics, but doesn't explain what output_format options exist, what mode means, what condense does, or what the return structure looks like. The sibling tools (scan_file, scan_directory) suggest this is part of a family, and the description references scan_file's behavior, but an agent couldn't confidently set all 14 parameters correctly based on this description alone.

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

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

Schema description coverage is 0%, so the description must compensate. It explains depth values (quick/normal/deep) and budget implications, and mentions focus reads elided content. It also explains the content and filename parameters implicitly via the stdin example. However, 14 parameters exist and many (mode, condense, body_only, output_format, show_complexity, show_decorators, show_docstrings, show_signatures, include_metadata) are not explained at all. The description covers maybe 4 of 14 parameters, so it partially compensates but leaves most parameters undocumented.

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 ('scan') and resource ('file content' or directory), and distinguishes itself from scan_file by handling content given directly (remote files, APIs, git blob, stdin) rather than paths. However, it doesn't explicitly name the sibling it differs from, and the opening 'Skeleton of files or a directory' is somewhat ambiguous about whether this tool handles directories (which scan_directory likely does).

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 for when to use this tool: when content is provided directly (remote files, APIs, git blob, stdin), and even provides shell command examples. It implies the alternative (scan_file) for path-based scanning, but doesn't explicitly state 'use scan_file for paths' or list exclusions. The sibling list includes scan_file and scan_directory, so the differentiation is mostly implicit.

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 and does a good job: it discloses pagination at 40 per page, states the page is reported, explains edge cases (no lead, empty match answer), and documents Python regex semantics including grep alternation. It doesn't cover auth requirements or failure modes, but for a search tool the disclosed behavior is substantial.

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 dense but not padded; the core purpose is front-loaded and every subsequent clause adds actionable detail about modes, regex behavior, pagination, and invocation. It reads as a long run-on block rather than structured sections, but for a tool with 11 parameters the length is mostly earned.

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 core search behavior, parameter mappings, and pagination are covered well, and there is enough detail for a first targeted code-search call. Yet with no output schema and 0% schema-description coverage, the complete omission of output_format, min_complexity, include_metadata, and type_filter allowed values leaves meaningful gaps.

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

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

Schema description coverage is 0%, so the description needs to compensate, and it maps many parameters: --names/name_pattern, --type/type_filter, --decorator/has_decorator, content_pattern, ref, limit, and offset. However, output_format, min_complexity, and include_metadata are never explained, and the CLI flag names require the agent to map them to schema property names.

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 first sentence clearly states the tool searches text across a directory with structural context, and later sentences distinguish text search from structure-name search. It doesn't explicitly name a sibling as the alternative, but it does position itself as the best first call and tells the agent to use it instead of Grep, which differentiates it from a plain text search tool.

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 says 'Best first call for a targeted question; use instead of Grep' and explains the main modes (content search vs structure search vs git ref), giving an agent a clear sense of when to invoke it. It doesn't provide negative usage guidance or explicitly contrast with sibling tools like scan_file_content, so it stops short of full 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 behavioral burden and meets it: it states exactly what is inspected, how each language's export rules are applied, what the diff header contains (direction, parts, line counts), and what `--part` prints. It also makes the read-only nature clear by describing printed output, so the agent can infer no destructive side effects.

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

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

The description is dense but front-loaded, leading with the core purpose before adding language rules, flags, and shell invocation. Every sentence contributes, though the invocation fallback sentence is slightly verbose for a tool definition.

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

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

For a 5-parameter tool with no output schema and no annotations, the description explains the primary output and main modes, but it leaves `ref` and `output_format` underspecified. An agent can make a correct basic call but may mis-specify output formats or the ref 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?

Schema description coverage is 0%, so the description must supply parameter meaning; it does for package_dir, --against, and --part, but leaves `ref` and `output_format` undocumented. The `ref` property is only vaguely implied by 'at a ref,' and `output_format` has no explanation at all.

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

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

The description opens with a specific resource ('public surface of a package directory at a ref') and enumerates the output ('every exported name with its signature, how it is exported and where it is defined'), making the purpose clear. It does not explicitly distinguish itself from sibling tools like scan_diff or find_divergence, so differentiation is implicit rather than stated.

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 concrete invocation patterns (`sct surface <package-dir>`, `--against REF`, `--part ID`) and explains the diff and part-printing modes, giving a clear sense of when each mode is appropriate. It does not, however, state exclusions or when to prefer a sibling tool.

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