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

Since no annotations are provided, the description carries the behavioral disclosure burden. It reveals output ordering (definitions first), output components (enclosing function and path:line), filtering behavior, and a key limitation (binding to a specific definition is not resolved). It does not explicitly state read-only behavior, but the overall query nature and lack of contradiction compensate partially.

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 economical: three sentences deliver the definition, scope exclusions, output details, resolution limitation, and runnable command. Every sentence contributes unique value, and the core meaning 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 tool with no annotations and no output schema, the description does a solid job explaining output structure and limitations. However, it omits semantics for `ref` and `output_format`, both of which are present in the schema and could affect invocation or result rendering. It is adequate for basic use but incomplete for full parameter understanding.

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

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

The input schema has no property descriptions, and schema coverage is 0%, so the description must explain the parameters. It does cover `name` and `directory` (via the CLI command), but it says nothing about `ref` or `output_format`. Two of the four parameters remain unexplained, leaving the agent to guess their meaning.

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

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

The description opens with a precise action and resource: 'Actual call sites of a function or method across a directory.' It further clarifies what is excluded (prose, comments, docstrings, string literals), making the tool's purpose unambiguous. The qualified-name behavior adds another distinguishing detail.

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 invocation patterns and defines the tool's scope boundaries: actual code call sites only, never textual mentions. It also explains when to use a qualified name to narrow definitions. It stops short of naming alternative sibling tools, but the usage context is clearly established.

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?

With no annotations, the description carries the full behavioral burden, and it does so thoroughly: it discloses expected stack overlap, residual commit semantics, the meaning of patch-equivalence, and explicitly warns that the result is 'a merge-order hint, not a verdict.' It also explains the significance of base markers.

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 is a single sprawling paragraph that mixes output semantics, caveats, and shell invocation. It is not poorly sized, but better structure (bullets or separation of output categories from usage) would improve scannability.

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

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

The description covers the tool's output structure and command invocation well, which is important given there is no output schema or annotations. However, it omits semantics for four optional parameters and does not provide sibling-tool guidance, leaving some ambiguity for complex calls.

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 clarifies the two required parameters through the command syntax `sct overlap <base> <branch>...`, but it leaves the optional parameters (`kind`, `path`, `repo`, `output_format`) unexplained. This is partial compensation, not complete.

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

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

The description clearly identifies the tool's purpose: comparing N branches against one base at their own merge-bases and reporting overlapping structures, names, commits, and base-inclusion criteria. It uses specific verbs and resources, but it does not explicitly distinguish itself from siblings like find_divergence or scan_diff.

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 the tool would be used (branch-overlap analysis) and even provides a shell invocation, but it does not state when to prefer this tool over alternatives such as find_divergence or scan_diff. There is no explicit when-not-to-use guidance.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the output nature (orientation summary, ~3-5k tokens, call-graph map) and scopes the tool to broad orientation rather than targeted queries. It does not mention side effects, read-only behavior, or how the tool behaves with atypical inputs, but the output and scope are 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 description is short and mostly front-loaded, and it includes a useful shell invocation plus fallback command. However, the opening sentence is syntactically confusing ('No command on a directory') and the relation to 'scan' is cryptic. The content earns its place, but the phrasing weakens the structure.

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 use case and output shape are described, but the tool has five parameters, no output schema, and no annotations. An agent cannot determine how to use or interpret depth, max_files, max_entries, or respect_gitignore. The missing parameter context makes the description incomplete for 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 description coverage is 0%, and the description essentially compensates for none of the five parameters. The only parameter hinted at is 'directory' via the shell example 'sct <dir>'; depth, max_files, max_entries, and respect_gitignore are entirely unexplained. This is a substantial gap for an agent trying to invoke the tool correctly.

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

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

The description clearly identifies the tool's purpose: it provides an orientation-level overview of a directory, including size, language mix, entry points, hot functions, and a call-graph map. It also distinguishes this from the file-tree-level 'scan' tool. However, the opening phrase 'No command on a directory' is garbled and obscures the intended meaning.

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 states the intended use case: first-time orientation over an unknown codebase, and explicitly says it is not for targeted questions. It also positions 'scan' as the tier below for file trees. It does not enumerate sibling alternatives or give precise when-not-to-use conditions for each sibling, but it offers enough routing guidance.

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

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

With no annotations provided, the description carries the 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 provided, the description carries the full burden of behavioral disclosure. It does mention elision markers (⟨…⟩ +N), focus behavior, and a self-levelling CONNECTIVITY note, which are useful. However, it does not state whether the operation is read-only, what the return structure looks like, how errors are handled, or any side effects. For a scan tool this is a notable gap.

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 dense single paragraph that mixes core functionality, parameter details, CLI commands, and a caveat about the PATH. It is not front-loaded and would benefit from bullet points or clear sections. It contains some redundancy (e.g., repeated mention of budget) and is more verbose than necessary.

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 15 parameters and no output schema, the description is incomplete. It does not describe the output format (beyond 'skeleton'), does not explain many parameters, and lacks guidance on expected return values or error conditions. While it covers some advanced features, the overall completeness is inadequate for an agent to use it confidently.

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 for all 15 parameters. It explains depth levels (quick/normal/deep), budget values, focus, and ref, but leaves delta, condense, output_format, show_complexity, show_decorators, show_docstrings, show_signatures, include_metadata, and caller entirely unexplained. The partial coverage is insufficient for the parameter count.

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 ('scan') and resource ('files or a directory') and describes the output as a skeleton with structure, signatures, and excerpts. It is not a tautology and provides a concrete picture of what the tool does, though it does not explicitly contrast itself with sibling tools like scan_directory or scan_file_content.

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 parameter-level guidance (budget for quick vs. exploration, focus for reading a node verbatim) but does not indicate when to choose this tool over its siblings. There is no mention of alternatives or exclusion criteria, leaving the agent to infer the tool's niche from the title and generic scan behavior.

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

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

No annotations are provided, so the description carries the full burden. It discloses depth levels (quick ~300 tokens, normal 1500, deep everything), elision markers (⟨…⟩ +N), and that focus reads elided content. It provides shell command examples. However, it does not cover all behavioral aspects like exact output format or error handling. Substantial insight but not exhaustive.

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

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

The description is dense but front-loaded with the main purpose. Each sentence adds detail about behavior, depth, or usage. It is not overly brief but is well-structured, with key information upfront and examples. It is appropriately sized for the tool's complexity.

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

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

Given the tool has 13 parameters, no output schema, and no annotations, the description provides a fair amount of context: core behavior, depth options, shell usage. However, it leaves many parameters undefined and relies on 'same as scan_file' which may not be obvious to the agent. For a complex tool, it is not fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains the depth parameter (quick/normal/deep), focus (reads elided content), and budget (token counts implied). It does not describe mode, output_format, condense, show_* flags, or other parameters. It adds value for key parameters but does not cover the majority of the 13 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 it scans file content given directly (remote files, APIs, git blob, stdin) and produces a skeletal structure with path:line, signatures, and excerpts. It explicitly mentions 'Content given directly' and 'same budget/depth and focus as scan_file', which differentiates it from the sibling scan_file (which presumably uses file paths). This is a specific verb+resource with clear sibling differentiation.

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 you have content directly rather than a file path. It provides shell command examples but does not explicitly name alternative tools or state 'use this instead of scan_file when providing content'. It gives clear context about the input type but lacks explicit 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 provided, the description carries the full burden of behavioral disclosure. It discloses pagination (40 per page, --limit/--offset, page stated), the empty-answer behavior ('an empty answer names the paths that match'), the grep alternation quirk ('grep's \| is read as alternation with a note'), and the CLI invocation fallback. It does not explicitly state that the tool is read-only, but the search semantics and 'use instead of Grep' strongly imply a non-mutating operation. The only minor gap is not stating whether results are sorted or how the tree output is structured, but the description is rich enough to earn a 4.

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: the first sentence establishes the core value proposition, and the rest adds mode distinctions, pagination, and CLI invocation. It is longer than ideal, but every sentence carries distinct information. The CLI invocation detail at the end is useful but could be trimmed or moved to a separate field; still, the structure is logical and scannable.

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

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

For a complex 11-parameter tool with no annotations and no output schema, the description covers the main usage modes, pagination, edge-case behavior (empty answer, grep alternation), and CLI fallback. It does not document output_format, min_complexity, or include_metadata, and it does not describe the return value shape beyond 'each hit shows its enclosing structure'. Given the tool's complexity, a 4 is appropriate; a 5 would require explicit coverage of every parameter and the 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?

Schema description coverage is 0%, so the description must compensate for the 11 parameters. It explains the key parameter groups: content_pattern (text with enclosing structure), name_pattern/type_filter/has_decorator (structure-name search), ref (git ref), limit/offset (pagination), and --names (which maps to name_pattern). It does not explain output_format, min_complexity, or include_metadata, but the core decision-driving parameters are covered. Given the high parameter count and zero schema coverage, this is a strong compensation effort, though not perfect.

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

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

The description opens with a specific verb ('Search') and resource ('text across a directory or one file') and immediately distinguishes itself from plain grep by adding structural context: each hit shows its enclosing structure and leads to definitions. It also names the sibling alternative ('use instead of Grep') and explains the --names mode, so an agent can tell exactly what this tool does and how it differs from a plain text search.

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

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

The description explicitly says 'Best first call for a targeted question; use instead of Grep', giving a clear when-to-use directive and naming the alternative. It also explains the two main modes (content_pattern vs name_pattern/type_filter/has_decorator) and the ref= option, so an agent knows which parameters to set for which intent. This is unusually complete 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 provided, the description carries the full burden of behavioral disclosure. It does this well by explaining language-specific export rules, namespace/module traversal, and that --against produces a diff with direction in the header. It does not mention output_format behavior or failure modes, but it provides substantial behavioral detail beyond a vague summary.

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, then adds language-specific context, diff mode, and shell usage. Its four sentences each add meaningful information, though the opening sentence is dense and the command examples could be more compact.

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 four parameters, no annotations, and no output schema, the description provides a strong semantic overview and even details the return content (names, signatures, export style, definition location). However, it omits explicit documentation for output_format and ref parameter mapping, leaving some ambiguity for a complex tool.

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

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

Because schema description coverage is 0%, the description must compensate for missing parameter documentation. It explains package_dir through the shell command, against through --against REF, and ref through 'at a ref', but it never explains the output_format parameter or enumerates its possible values. This is partial compensation with clear gaps.

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

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

The description clearly states the tool's function: it shows the public surface of a package directory at a ref, listing every exported name with its signature, export style, and definition location. This is specific enough to distinguish it from sibling tools like list_directories or scan_directory, though it does not explicitly name an alternative to contrast against.

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 shell invocations and explains the --against REF diff mode, so an agent can understand how to run it. However, it does not explicitly state when to prefer this tool over siblings such as scan_diff, overlap, or scan_directory, leaving the decision to inference.

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