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 output structure (enclosing function and path:line, definitions first), a limitation (definition binding not resolved, and the result says so), and scoping constraints (only actual call sites, not prose). It also ties to a statically resolved import graph, giving deeper context.

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 wasteful—every sentence adds a distinct fact (scope, output, limitation, usage, shell alternatives). It's front-loaded with the core purpose and ends with practical invocation details. While slightly long, it is structured informationally and avoids redundancy.

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

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

The description covers the main behavior, limitations, and usage for two of four parameters, and gives output hints. However, it leaves `ref` and `output_format` unaddressed, and since there is no output schema, the return format description is only partial. An agent would need to infer or probe to fully understand the tool's interface.

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 four parameters. It explains `name` (can be a function/method name or a file path) and `directory` via the shell example, but gives no information about `ref` or `output_format` (its purpose, allowed values, or defaults). This is a significant 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 states the tool's role with precision: it finds actual call sites of a function/method across a directory, explicitly excluding prose/comments/docstrings/string literals. It lists the exact questions it answers (who calls this, usages/references, file imports) and differentiates itself from the broader scanning siblings by focusing on call sites.

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 scenarios for when to use it ('who calls this function; find usages and references; which files import this file') and includes concrete shell invocations. It does not explicitly state when not to use it or name alternative tools, but the usage context is clear enough for an agent to decide.

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 clearly states that the tool is a review hint, not a verified bug list, and that silence is a valid answer on consistent codebases. It also includes a CLI invocation hint. However, it does not explicitly mention side effects (though scanning is likely read-only) or error handling, which prevents a perfect score.

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 includes an extraneous shell command (sct --help) that is not essential for an MCP tool definition. The core explanation is clear, but the added CLI hint and repetitive phrasing ('functions that break a pattern their siblings follow' appears twice) make it less concise than it could be. A tighter version would front-load the core purpose and omit irrelevant instructions.

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

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

The description explains the tool's purpose, output (functions breaking patterns), and the special case of silence. It covers the essential context for a scan tool with three parameters. However, it lacks explicit guidance on when to use this tool versus similar siblings, and the inclusion of a CLI command that may not be applicable in all environments adds noise. Overall, it is adequate but 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?

The input schema has 100% description coverage for all three parameters (directory, max_findings, respect_gitignore), so the description does not need to add parameter details. The description does not provide additional semantic value beyond the schema, so the baseline of 3 applies. The shell command hint is unrelated to parameter semantics.

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

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

The description clearly states the tool's purpose: finding peer divergence in a directory, specifically functions that break a call pattern their siblings follow. It gives a concrete example and distinguishes itself from a bug list, making it unambiguous. The verb 'find' and resource 'divergence' are specific, and it effectively communicates the core functionality.

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 it is for review purposes ('A review hint, not a verified bug list') and mentions it returns silence on consistent codebases, but it does not explicitly name alternatives or state when to use this tool versus siblings like scan_directory or search_structures. There is no clear 'when not to use' guidance, so the agent must infer usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers. It explains precisely how the traversal works: signature/body changes are followed, renames are paired by identical body, file moves are followed, and commits touching the file but not the structure are counted but not listed. This is rich behavioral detail far beyond a generic 'history' statement.

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 includes valuable information like rename handling, file moves, and the Python fallback command, but the first sentence is grammatically awkward and hard to parse: 'One structure followed backwards through the commits that touched its file: ...' The structure is not front-loaded or scannable; the core purpose takes several sentences to emerge clearly.

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 that there is no output schema and no annotations, the description provides a surprisingly complete picture: it explains what is followed, what is counted vs listed, and gives both common invocation forms including a fallback for when `sct` is not on PATH. It falls short only by not describing the output format (`tree` default) or the `repo` parameter, but the core usage context is well covered.

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 schema's silence. It does partially explain the `location` parameter through examples (`<path::name>` and `<path:line>`) and shows how to pass `--ref REF`. However, it does not explain `repo` or `output_format` at all, leaving 2 of 4 parameters undocumented in both schema and 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 identifies the tool's purpose: track a code structure (function/class) backwards through commits, answering 'which commits changed this function or class, and when.' It uses a specific verb ('followed backwards') and a specific resource ('structure'), and the use-case list helps distinguish it from generic git/history tools. However, it does not explicitly distinguish itself from sibling tools like find_divergence or scan_diff, so it is not a 5.

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 use cases: 'which commits changed this function or class, and when; git log or git blame for one function; how a function evolved across commits.' This implies when to use the tool, but it does not state when not to use it or compare it with sibling tools. It offers shell invocation examples, which helps, but the usage guidance remains implicit rather than explicit.

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?

The description discloses some behavior, such as 'Elided content is marked ⟨…⟩ +N' and depth-based token budgets, but it is inconsistent (e.g., 'Skeleton of files' vs. 'Folders only, no files') and does not clarify side effects, permissions, or the exact output shape. With no annotations, the description carries full burden and fails to give a coherent behavioral picture.

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 long, rambling, and mixes tool-specific behavior with generic CLI usage instructions ('In your shell: sct --help'). It is not front-loaded; the core operation is buried in the middle. Every sentence does not earn its place, and the irrelevant CLI help paragraph should be removed.

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

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

For a tool with 3 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain what the returned tree looks like, how max_depth affects output, or how respect_gitignore changes behavior. The mention of elision markers is useful but not enough to make the tool safely callable.

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 detail all three parameters (directory, max_depth, respect_gitignore) but does not. It vaguely mentions '--depth quick' and token budgets without mapping to the max_depth parameter, and it never addresses respect_gitignore. This is a critical gap for an agent 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 suggests this tool lists a directory tree with one-line gists ('A directory gives the tree with one-line gists') and claims 'Folders only, no files', but it opens with a vague phrase about 'skeleton of files or a directory' that muddies the resource. It does not explicitly state the verb+resource in a focused way nor differentiate from siblings like scan_directory or preview_directory.

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

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

No explicit when-to-use or alternative-selection guidance is provided. The 'Answers:' section lists general capabilities of an underlying CLI tool, not conditions for choosing this tool over its siblings. The only implicit hint is 'Folders only, no files', which is not framed as a decision rule.

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 transparency burden and does well: it explains output parts, base(~/+/-) markers, the patch-equivalence caveat, and that the result is a hint rather than a verdict. It does not explicitly state whether the tool is read-only, but the analytical framing implies no mutation.

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 long but dense, with no filler. The most important framing ('N branches against one base, each at its own merge-base') is front-loaded, and each sentence contributes semantic detail, caveats, or invocation instructions. The inline Python fallback is extra but useful.

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 output schema and no annotations, the description is quite complete: it names the output parts, explains markers and caveats, lists the questions it answers, and gives an invocation. The main gaps are the unexplained optional schema fields and the lack of a precise output shape beyond the first-line summary.

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 meaningfully clarifies the required base and branches parameters via the `sct overlap <base> <branch>...` syntax and maps `--part ID` to the part parameter. However, it leaves `kind`, `path`, `repo`, and `output_format` unexplained, which is a notable gap given the schema offers no descriptions.

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

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

The description clearly defines what the tool does: it compares N branches against one base at each branch's own merge-base and reports structures touched by 2+ branches, shared commits, base containment, and a merge-order hint. This distinguishes it from single-branch diff or divergence siblings by emphasizing multi-branch conflict and ordering questions.

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 states concrete use cases: determining branch conflicts, deciding merge order, and identifying commits shared by pull requests. It also warns that the output is 'a merge-order hint, not a verdict.' It does not explicitly name alternative sibling tools or say when not to use this tool, so it falls short of full guidance.

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

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

With no annotations, the description carries the burden. It discloses the output length (~3-5k tokens), the format (line one lists parts with line counts), and that it fetches one part alone via the 'part' parameter. It also reveals that the tool runs a shell command (sct) and provides the fallback invocation. This is helpful but does not disclose side effects (likely read-only) or error handling, which is acceptable for an orientation 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 moderately sized and front-loads the core purpose. It is structured into a few sentences covering orientation, output format, use cases, and shell invocation. Some redundancy (e.g., repeating the fallback command) but generally 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's complexity (6 params, no schema coverage, no output schema), the description provides a reasonable overview: output length, parts list, use case, and shell command. It lacks detailed parameter explanations (e.g., depth values) but provides enough to get an agent started. For an orientation tool that typically uses defaults, this is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'part' parameter (to fetch one part alone) and mentions depth, max_files, max_entries implicitly through limits. However, it does not explain the exact semantics of depth (deep vs shallow), max_entries, or respect_gitignore beyond what the schema field names imply. The description adds minimal value for parameters beyond the schema.

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

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

The description clearly states the tool provides an orientation overview of a codebase, including size, language mix, entry points, hot functions, and a call-graph map. This distinguishes it from sibling tools like scan_directory (which likely does a file tree scan) and list_directories (which lists directories). However, the description is somewhat abstract and could be more explicit in stating it previews a directory's structure and 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?

The description explicitly states when to use this tool: for first-time orientation of an unknown codebase, not for targeted questions. It also contrasts with the file tree (which is the tier below via scan). It does not name a specific sibling alternative but implies that scan_directory is for the tree. This is clear guidance for typical use cases.

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 present, the description bears full responsibility for behavioral disclosure. It explains the core computation and possible outcomes (same place, renamed with identical body, or gone with nearest names), which is genuinely useful. However, it does not explicitly state that the operation is read-only, does not describe the response/output format, and does not discuss error cases, leaving meaningful gaps for a tool without annotation safety hints.

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 efficient: it defines the operation, the semantic outcomes, the use cases, and a concrete shell invocation, all in a few sentences. The command example is front-loaded with the core syntax and includes a fallback invocation, making every sentence earn its place without padding.

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

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

For a 5-parameter tool with no output schema and no annotations, the description covers the essential semantics of location, ref_from, and ref_to, and handles the likely main use cases. But it omits repo and output_format entirely, and does not explain what the returned output looks like or what 'tree' format means. An agent could make the most common call correctly, but not all supported calls 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. It explains the location input format ('path:line' or 'path::name') and illustrates --from/--to usage with shell examples, which maps well to ref_from and ref_to. However, repo and output_format are never mentioned, and the defaults (e.g., ref_to defaults to WORKTREE) are only implicitly suggested by the example. This is partial but not complete compensation for the empty 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 opens with a specific verb 'Translate' and the exact resource types ('path:line' or 'path::name'), then explains the mapping between refs. It differs clearly from sibling tools like find_divergence or search_structures by focusing on cross-commit location translation rather than scanning or diffing.

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 explicit use cases: 'where a line or function is at another commit' and 'map a line number from one commit to another', which tells an agent when to invoke it. It does not name alternative tools or exclusion conditions, so it lacks the explicit when-not-to-use guidance, but the context is clear enough for routing.

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

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

With no annotations provided, the description carries the full burden. It discloses substantial behavioral details: the default merge-base behavior, the --no-merge-base alternative, per-file change categories (+/~/=/-), folding of identical signature deltas, skeleton files, coverage line behavior, and the --review flag being off by default. It doesn't mention performance or error behavior, but the disclosed behavior is rich and specific.

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 information-dense and front-loaded with the core diff semantics, but it is long and somewhat stream-of-consciousness. The shell command example at the end is useful but the sentence 'ref vs the working tree, or ref vs ref2; review=True appends the review tail' partially repeats earlier content. Every sentence carries information, but the structure 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?

Given the tool's complexity (7 params, no output schema, no annotations), the description is quite complete. It explains the diff modes, per-file change categories, the coverage line, the review feature, and provides shell usage. It doesn't document budget or output_format, but the core semantics an agent needs to select and invoke the tool are present.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the core ref/ref2 semantics ('One ref = that ref vs the working tree', 'Two refs = A...B against their merge-base'), the review flag ('--review appends candidate dead/orphan/drift'), and no_merge_base ('--no-merge-base compares the tips'). It doesn't explicitly explain budget or output_format, but the most critical parameters are covered.

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

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

The description clearly states the tool performs a structural diff between refs, with specific verbs and resources: 'Structural diff between refs', 'One ref = that ref vs the working tree', 'Two refs = A...B against their merge-base'. It distinguishes itself from git diff and sibling tools by focusing on per-function structural changes rather than line-level diffs.

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 when to use it: 'Use instead of git diff for review and what changed questions' and lists concrete use cases: 'what changed between two commits or branches, per function; review the changes of a pull request or branch; local changes against HEAD'. It also provides shell command examples with sct diff, which is actionable 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, and it does substantial work: token-budget estimates per depth, elision marker '⟨…⟩ +N', tree output with code health and churn labels, and git-ref support via 'ref='. It does not mention side effects or permissions, but as a read-oriented scanning tool this is a minor gap rather than a fatal one.

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 with the core concept, but it wanders into run-on sentences and repeats the directory-tree idea twice. The shell invocation is useful, but the overall paragraph would be clearer with bullets or separate sections for behavior, parameters, and usage.

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, this description is not complete enough. It covers depth, ref, elision, and high-level output shape, but leaves many parameters undefined, and does not explain mode, output formats, filtering, or metadata options. An agent would still need to guess or probe to use the tool fully.

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 12 parameters. It explicitly explains only depth and ref, and implies directory and directory-tree output. Parameters such as mode, pattern, delta, max_files, exclude_patterns, include_metadata, respect_gitignore, output_format, and caller are left completely undocumented. This is a significant semantic 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 clearly states what the tool produces: a skeleton of files with path:line, signatures/titles, and excerpts, or a directory tree with one-line gists. It also lists specific answerable questions (read file contents, outline a file, list functions/classes). However, it does not explicitly differentiate this tool from sibling tools like scan_file, scan_file_content, or preview_directory, so its boundary is slightly blurred.

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 use cases: reading file contents, outlining files, listing functions/classes, and reading a function by name. It also says 'Replaces Glob/ls for all file types,' which signals when to prefer it. It lacks explicit when-not-to-use guidance or alternatives relative to the sibling set, so it does not fully meet the highest bar.

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 of behavioral disclosure. It explains output shape (skeleton/tree with path:line and gists), token budgets per depth, elision marker '⟨…⟩ +N', focus behavior, body_only, ref, and the conditional connectivity note. It does not discuss errors or side effects, but for a read/scan-style tool this is substantial disclosure.

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 one long dense paragraph with many stacked clauses, making it information-heavy but not easy to scan. It does front-load the core concept and ends with a useful CLI invocation, but it would benefit from clearer segmentation or bullet-style 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?

For a 16-parameter tool with no annotations and no output schema, the description covers key use cases, budget semantics, focus behavior, and output elision, which is reasonably complete. However, several parameters remain underspecified and the directory-mode overlap with scan_directory is not resolved, leaving notable 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 must compensate for all 16 parameters. It adds real semantics for depth, budget, focus, body_only, and ref, but leaves many parameters like delta, condense, caller, output_format, and the show_* family unexplained. Some are inferable from their names, but the compensation is incomplete.

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 a file/directory to produce a skeleton with line numbers, signatures or titles, and condensed excerpts. It is clear about what it returns and even lists the questions it answers, but it does not explicitly differentiate from sibling tools like scan_file_content or scan_directory, and it admits both file and directory targets despite its 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 'Answers:' enumeration gives concrete use cases such as reading file contents, outlining a file, listing functions/classes, and reading a single source node. It also mentions exploration vs quick-look budgets. However, it never explicitly says when to prefer this tool over its many siblings or what exclusions apply, so the guidance is implied rather than explicit.

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 disclosure burden and does substantial work: it explains output shape (skeleton, path:line, directory tree gists), elision marker '⟨…⟩ +N' and focus behavior, and per-depth token budgets (quick 300, normal 1500, deep). It omits edge-case behavior like error handling or network failures, but the core read-only 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 is dense and every clause adds information, but it is a single run-on paragraph that mixes output format, budgets, elision, use cases, and shell commands without clear separation. The opening phrase 'Skeleton of files or a directory' is confusing as a purpose statement and reduces clarity.

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 14 parameters, no output schema, and no annotations, the description covers the core use cases and key behavioral parameters but leaves many schema fields and edge behaviors unaddressed. An agent can likely call the tool for reading or outlining directly supplied content, but would be guessing about output_format variants, condense behavior, and the display toggles.

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 meaningfully explains depth (quick/normal/deep with token approximations), budget, focus, and indirectly content and filename via 'Content given directly' and the `--as <path>` CLI form. However, most optional toggles—mode, condense, body_only, output_format, show_*, include_metadata—are left unexplained, so compensation is only partial.

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 action as scanning directly supplied content and extracting structural information: 'every structure with path:line, signature or title' and the 'Answers:' list covering read contents, outline, list functions/classes, and show source by name. It distinguishes from scan_file by noting that 'content [is] given directly' rather than via filesystem path, though it does not explicitly name the sibling as the alternative.

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 context for when to use this tool: when content is supplied directly from remote files, APIs, git blobs, or stdin. It also provides concrete shell invocations (`sct scan - --as <path>`, `sct focus - --as <path> <name>`) and explains depth/budget behavior, but it does not explicitly say when not to use it or directly contrast it with scan_file/scan_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 transparency burden and discharges it thoroughly: it discloses match semantics (Python regex, grep `\|` read as alternation with a note), edge-case behavior (empty answer names paths and the alternate reading; no-lead cases are explicitly stated), output shape (one row per structure, decorators on the row), pagination (40 per page, page stated, --limit/--offset), and git-ref search. This far exceeds what annotations would typically provide.

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

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

The description is a single dense run-on paragraph with no internal structure and noticeable repetition (the content_pattern vs name_pattern/type_filter/has_decorator distinction is stated twice). Every sentence does carry information, and the core purpose is front-loaded, but the wall-of-text format imposes a heavy parsing burden on the agent.

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 an 11-parameter tool with zero schema descriptions, no annotations, and no output schema, the description is remarkably complete on the main search paths: modes, filters, pagination, regex semantics, edge cases, and shell invocation are all covered. It is not a 5 because three parameters (output_format, min_complexity, include_metadata) remain undefined and the CLI-flag phrasing requires the agent to infer the schema-property mapping.

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 is the sole source of parameter meaning, and it does explain the behavioral core: content_pattern, name_pattern, type_filter, has_decorator, limit/offset, and ref all receive semantic content including their interplays (e.g., --decorator only operates with --names). However, it uses CLI flag names rather than schema property names (--names vs name_pattern, --type vs type_filter), forcing the agent to infer the mapping, and it leaves output_format, min_complexity, and include_metadata completely unexplained.

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 job — searching text across a directory or single file and returning hits with enclosing structural context plus leads to definitions. It also positions the tool against alternatives ('Best first call for a targeted question; use instead of Grep') and enumerates its two answer types: finding where a function/class is defined and finding text in code. The verb-resource-scope combination is unambiguous despite the fragment-style opening sentence.

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?

Explicit when-to-use guidance is present: 'Best first call for a targeted question; use instead of Grep,' followed by the specific question types the tool answers. It stops short of a 5 because it names no sibling tool in the current toolset and gives no when-not-to-use exclusions (e.g., when a plain content scan via scan_file_content 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?

The description discloses several behavioral traits: it looks through namespaces/modules, applies language-specific export rules, and supports diffing with --against. It also explains the output structure (header with direction and parts, line counts). However, it doesn't mention potential side effects or performance characteristics, though as a read-only analysis tool this is less critical. No annotations are provided, so the description carries the full burden, and it does a good job.

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 well-organized, front-loading the core purpose and then explaining the diff mode and use cases. It's longer than ideal but every sentence adds value, covering language-specific rules, output structure, and shell usage. The structure could be slightly improved by separating the diff explanation from the core purpose, but it's still effective.

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

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

Given the tool's complexity (5 parameters, no output schema, no annotations), the description is quite complete. It explains the main use cases, the diff mode, and even provides shell invocation examples. It doesn't detail the exact output format for the tree mode, but the description of 'every exported name with its signature, how it is exported and where it is defined' gives a clear picture. The main gap is the lack of explicit parameter descriptions for output_format and part, but these are partially covered.

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 the key parameters: package_dir (the package directory), ref (the ref to analyze), against (the ref to diff against), and part (which part of the diff to print). It doesn't explicitly explain output_format, but the default 'tree' is implied by the description's focus on structure. This is strong compensation for the lack of schema descriptions.

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

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

The description clearly states the tool's purpose: it shows the public surface of a package directory at a ref, including exported names, signatures, export mechanism, and definition location. It also distinguishes itself from siblings by focusing on the public API surface rather than general file/directory scanning or diffing.

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 explains when to use this tool: to answer questions about a package's public API, exported names, and API changes between versions. It also provides concrete shell usage examples and mentions the --against flag for diffs, which helps an agent decide when to use this tool versus alternatives like scan_diff or find_divergence.

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