Skip to main content
Glama
raultov

knot

by raultov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Hybrid

List indexed repository files

list_files
Read-onlyIdempotent

List files in indexed repositories by path prefix or glob, showing entity counts. Use to learn codebase layout before running scoped searches.

Instructions

Read-only listing of the files an indexed repository carries, with entity counts and deterministic order. Answers 'list every file under src/hooks' or 'which files live in src/api/**' without prior path knowledge.

Usage: Use this BEFORE 'search_hybrid_context' when you do not know the codebase layout; then pass the same prefix to the search's optional 'path' parameter to scope results to those files. Do NOT use this to enumerate entities — use 'explore_file' on a file from this listing for its anatomy.

Behaviour & Return: Read-only query with no side effects. Returns a Markdown table with columns: REPOSITORY, FILE, ENTITIES, ordered by (repository, path). When output exceeds 2000 files, the table displays the first 2000 matches alongside a truncation notice stating the exact total when known, or an explicit lower bound when the scan stopped early. When nothing matches the prefix, returns 'No indexed files matched the given path'.

Parameter guidance: 'path' is optional. PREFERRED: a repo-relative directory prefix (e.g. 'src/api') matched on a path boundary, or a glob ('src/**/*_test.rs'). Prefixes and globs page all indexed files in pages with per-page boundary filtering without dropping candidates. Absolute paths under the local checkout are accepted and normalized like 'explore_file'. Omit to list every indexed file (capped; the reply notes truncation).

Parameter guidance: 'repo_name' scopes the listing. Accepts a single repository name or a comma-separated list; include it when several indexed repositories may share path shapes.

Supports all languages indexed by knot.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathNoOptional repo-relative directory prefix (e.g. 'src/api', matched on a path boundary) or glob pattern (segments: `*` segment wildcard, `**` any depth, `?` one char). Absolute paths under the local checkout are accepted and normalized like 'explore_file'. Omit to list every indexed file.
repo_nameNoOptional but HIGHLY RECOMMENDED: repository scope. Accepts a single repository name (`'my-repo'`), a comma-separated list (`'repo-a,repo-b'`), or `'all'` (or `'*'`) to query every indexed repository. Include it when several indexed repositories may share path shapes.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.9.6

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already mark readOnly/idempotent/non-destructive, but the description adds behavioral details beyond hints: deterministic ordering by (repository, path), a 2000-file cap with a truncation notice showing exact or lower-bound totals, and the exact empty-result string. There is no contradiction with the annotations.

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 long but deliberately sectioned (Usage, Behaviour & Return, Parameter guidance) and front-loaded with its core purpose. Some prose repeats annotation facts and schema descriptions, so it is not maximally tight, but the structure keeps the extra length navigable and each section earns its place.

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

Completeness5/5

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

For a two-parameter read-only listing tool, the description covers intended use, chaining with siblings, exact return columns and order, truncation behavior, empty-match response, and both parameter semantics. Since there is no output schema, explicitly documenting the return format and edge cases is valuable and fully handled.

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

Parameters5/5

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

Schema coverage is 100% so the baseline is 3, but the description goes well beyond schema text: it explains path-boundary prefix matching, glob semantics, paging behavior ('per-page boundary filtering without dropping candidates'), absolute-path normalization, and when repo_name is needed (shared path shapes across repositories). This materially improves call construction.

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 first sentence states a specific verb ('listing'), a specific resource ('files an indexed repository carries'), and two distinguishing outputs (entity counts, deterministic order). It explicitly distinguishes its contribution from search_hybrid_context and explore_file, so it cannot be confused with siblings.

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 'Usage' section states concretely when to use it ('BEFORE search_hybrid_context when you do not know the codebase layout'), how to chain it with that sibling, and an explicit negative instruction ('Do NOT use this to enumerate entities — use explore_file'). This is explicit, actionable routing.

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