proofcut

by tydude001

Overview Schema Source Related Servers Discussions Admin

Python

Local

list_media

Read-onlyIdempotent

Discover footage files available for import from a source directory, with recursive search and already-imported flags.

Instructions

List media files under source_dir that import_media could register.

What hands an unattended agent source paths on a real job, since an agent confined to proofcut's tools (the agent panel's --tools ToolSearch) has no directory listing of its own (HISTORY.md § The seventh queue item, decided and built). A filename filter, not a probe — import_media is still what decides a file is actually usable. Each entry's already_imported is checked against this project's own registered clips, so a repeated call does not keep re-suggesting footage already on the asset list. source_dir names wherever the footage lives and is not confined to the project.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	No	The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing.
`recursive`	No	Walk subdirectories too. On by default.
`source_dir`	Yes	The directory to list. It names where footage lives rather than which project, so it is deliberately not confined to the bound project.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.25.0Sep 16, 2026

removedInput schema / properties / path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / path / description

Added value: +"The project directory to act on. Omit it — the usual case — when this server is bound to a project (started as `proofcut -C DIR mcp`, or inside a project; `ping` says which): it then resolves to that one bound project, a relative path resolves against it, and a path outside it is refused by name. Unbound, `path` is the whole address and omitting it refuses rather than guessing."

removedInput schema / properties / path / title
```
Removed value: -"Path"
```

addedInput schema / properties / path / type

Added value: +[
+  "string",
+  "null"
+]

addedInput schema / properties / recursive / description

Added value: +"Walk subdirectories too. On by default."

removedInput schema / properties / recursive / title
```
Removed value: -"Recursive"
```

addedInput schema / properties / source_dir / description

Added value: +"The directory to list. It names where footage lives rather than which project, so it is deliberately not confined to the bound project."

removedInput schema / properties / source_dir / title
```
Removed value: -"Source Dir"
```
removedInput schema / title
```
Removed value: -"list_mediaArguments"
```

First observedv0.24.0Sep 15, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: `already_imported` is checked against the project's registered clips, repeated calls avoid re-suggesting existing footage, and `source_dir` is not confined to the bound project. No contradiction with annotations.

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 first sentence is strong and front-loaded, but the second paragraph is verbose and includes tangential references to HISTORY.md and panel flags that do not help an agent call the tool. The content is relevant overall, but it could be trimmed without losing usefulness.

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 output schema and full parameter documentation, the description provides enough context for correct invocation: what the tool lists, how `already_imported` is determined, and that `source_dir` is intentionally not project-constrained. Nothing critical for selecting or using the tool is missing, though the phrasing could be more direct.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline of 3 applies. The description's note about `source_dir` largely restates what the schema already says; it adds behavioral context but no new per-parameter semantic details beyond the schema.

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 the exact verb, resource, and scope: "List media files under `source_dir` that `import_media` could register." It also distinguishes this from being a probe, clarifying that it is a filename filter and not the tool that decides usability.

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?

The description explains the main use case: handing source paths to an unattended agent that has no directory listing of its own. It also gives an important exclusion: this is not a probe, and `import_media` remains the authority on whether a file is usable. It could be tighter by naming sibling alternatives explicitly, but the guidance is clear.

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

Deploy Server