Skip to main content
Glama
whatanaiceguy

kuruitsugizaki

by whatanaiceguy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

samples

Idempotent

Find drum, one-shot, loop, and break audio files by folder, path query, or duration, then use returned paths in project_write to load samplers or audio clips.

Instructions

List samples for drums, one-shots, loops and breaks; a sample's path (its folder plus its name) goes into project_write as a sampler's or audio clip's path. Call it before choosing any sample, and take samples only from folders the user gave.

No arguments: the user's sample folders, each with its subfolders and how many audio files each holds. With query, the samples whose path matches; with folder, that folder's subfolders and files, and a query stays inside it. Returns {total, results: {folder: [[name, seconds]]}}; past limit the list is an even spread across folders.

When config sample_folders is not set it returns {ok: false, error}: ask the user where their samples are and set it with config (a folder or a JSON list), or 'none' when they have none, which makes FL's factory packs the source; the answer is kept.

Changes no sample file; FL need not run. It caches folder listings in tmp/samples/index/; measure also writes tmp/samples/.tsv.

Input Schema

NameRequiredDescriptionDefault
limitNoat most this many samples
queryNowords that must all appear in the path below the sample folder, case-insensitive, any order, any depth, e.g. 'snare tight'
folderNoone folder to look into: absolute, below a sample folder, or %FLStudioFactoryData%/...; omit for all sample folders
measureNoalso write the folder's own audio files' levels, width, onsets and centroid to tmp/samples/<folder>.tsv
max_foldersNoat most this many folders in a folder listing, whole levels from the top
max_secondsNokeep samples at most this long, e.g. 1 for one-shots
min_secondsNokeep samples at least this long

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.5
    • changedInput schema / properties / max_folders / description
      Previous value: -"at most this many folders in a folder listing: whole levels from the top, the last level shared across its parents"New value: +"at most this many folders in a folder listing, whole levels from the top"
    • changedInput schema / properties / query / anyOf
      Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Changed4 schema fields changedv0.4.2
    • changedInput schema / properties / folder / description
      Previous value: -"one folder to look into; omit for all sample folders"New value: +"one folder to look into: absolute, below a sample folder, or %FLStudioFactoryData%/...; omit for all sample folders"
    • changedInput schema / properties / max_folders / description
      Previous value: -"at most this many folders in a folder listing"New value: +"at most this many folders in a folder listing: whole levels from the top, the last level shared across its parents"
    • changedInput schema / properties / measure / description
      Previous value: -"also measure the folder's own audio files into tmp/samples/<folder>.tsv"New value: +"also write the folder's own audio files' levels, width, onsets and centroid to tmp/samples/<folder>.tsv"
    • changedInput schema / properties / query / description
      Previous value: -"words that must all appear in the path, case-insensitive, any order, e.g. 'snare tight'"New value: +"words that must all appear in the path below the sample folder, case-insensitive, any order, any depth, e.g. 'snare tight'"
  3. Addedv0.4.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, and the description reconciles that by stating 'Changes no sample file' while disclosing the actual writes: folder-listing cache in tmp/samples/index/ and a TSV when measure is set. It also documents the failure shape {ok: false, error} and that FL need not be running — context the annotations cannot express. Return-record format and truncation behavior are covered too, leaving only minor gaps like cache invalidation timing.

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?

Core purpose and the project_write handoff are front-loaded, and the paragraph breaks map to distinct modes (default, filtered, error, side effects). It is denser than it needs to be in places — semicolon-chained clauses and the tmp/ path details could be tightened — but no sentence is pure filler.

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 7-parameter, all-optional tool with no output schema, the description supplies the return shape ({total, results: {folder: [[name, seconds]]}}), the error shape, truncation policy, and side effects. An agent has everything needed to call it correctly on the first try.

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 100%, so the schema baseline already carries per-parameter meaning. The description nonetheless adds non-obvious semantics the schema omits: that the no-argument form lists all sample folders with subfolder counts, that a query stays confined inside a supplied folder, and that past limit the results are an even spread across folders rather than a truncated head.

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?

Opens with a specific verb and resource ('List samples for drums, one-shots, loops and breaks') and immediately connects its output to a sibling ('a sample's path ... goes into project_write'). An agent can distinguish it from presets, plugins, and project_read without opening any schema.

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?

Explicit sequencing ('Call it before choosing any sample'), an explicit constraint ('take samples only from folders the user gave'), and a documented recovery path when config sample_folders is unset (ask the user, then set it with config, or 'none' for factory packs). It names the alternative tool and the condition that selects it.

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