Skip to main content
Glama
mariusei

Scantool - File Scanner MCP

by mariusei
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Search Structures

search_structures

Search source code structures across a directory to find functions, classes, or text with enclosing context and definition leads. Filter by name, type, decorator, or content pattern.

Instructions

Text across a directory (or one file) with structural context: each hit shows its enclosing structure, plus leads to where matched names are defined; when no lead exists it says so. --names matches structure names instead of text; an empty answer names the paths that match and what the other reading finds (the pattern as text, or as names). The pattern is a Python regex; grep's \| is read as alternation with a note. --type filters which structures are reported; --decorator RE (with --names) keeps structures with a matching decorator and answers one row per structure, decorators on the row. 40 structures per page, --limit/--offset for the rest, and the page is stated. content_pattern finds text with its enclosing function/class/section plus leads to definitions; name_pattern/type_filter/has_decorator find structures; ref= searches at a git ref. Best first call for a targeted question; use instead of Grep. Answers: find where a function or class is defined; find text in code across files. In your shell: sct search <dir> <pattern> (if sct is not on PATH, "/app/.venv/bin/python" -m scantool.cli replaces sct).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
refNo
limitNo
offsetNo
directoryYes
type_filterNo
name_patternNo
has_decoratorNo
output_formatNotree
min_complexityNo
content_patternNo
include_metadataNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.26.0
    • addedInput schema / properties / ref
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
  2. Changed3 schema fields changedv0.23.0
    • addedInput schema / properties / include_metadata
      Added value: +{
+  "default": true,
+  "type": "boolean"
+}
    • addedInput schema / properties / limit
      Added value: +{
+  "default": 40,
+  "type": "integer"
+}
    • addedInput schema / properties / offset
      Added value: +{
+  "default": 0,
+  "type": "integer"
+}
  3. Changed1 schema field changedv0.20.1
    • addedInput schema / additionalProperties
      Added value: +false
  4. First observedv0.19.4

TDQS

A4.4/5.0
Behavior5/5

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.

Conciseness3/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Deploy Server

Other Tools