Skip to main content
Glama
mariusei

Scantool - File Scanner MCP

by mariusei
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Surface

surface

Show the public API of a package directory: every exported name, signature, export method, and definition location. Diff against another ref to identify API changes between versions.

Instructions

The public surface of a package directory at a ref: every exported name with its signature, how it is exported and where it is defined. Each language applies its own rule: Python's all, lazy tables and re-export chains; Rust's pub and lib.rs re-exports; TypeScript's index exports; Go's exported identifiers; visibility keywords elsewhere; a namespace or module is looked through. --against REF prints the surface diff; the header states the direction (A → B) and names its parts (added, changed, moved, removed) with line counts; --part ID prints one part alone. Answers: the public API of a package or module; exported names and where each is defined; API changes between two versions. In your shell: sct surface <package-dir> or sct surface <package-dir> --against REF (if sct is not on PATH, "/app/.venv/bin/python" -m scantool.cli replaces sct).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
refNo
partNo
againstNo
package_dirYes
output_formatNotree

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.28.0
    • addedInput schema / properties / part
      Added value: +{
+  "default": "",
+  "type": "string"
+}
  2. Addedv0.26.0

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server

Other Tools