Skip to main content
Glama
Txpple

fvtt-mcp-molten5e

by Txpple
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

configure-soundscape

Author and manage a scene's atmospheric sound sets: randomized interval one-shots or crossfaded ambient loops. Use library templates or custom pools, with strict validation and live status.

Instructions

Author a scene's atmospheric SOUND SETS — the house module fvtt-mod-soundscape (#6), which does what core Foundry cannot: a POOL of small audio files played at randomized intervals with silence between (a crow, quiet, a distant dog), or overlapped into a seamless crossfaded bed. AmbientSound placeables are positional single-file loops and Playlists have no silence-with-variation, so neither covers this. A scene carries any number of sets, stacked and independent. Actions: "list" (what the scene has, plus what would be playing right now and why a set is idle), "library" (browse the prebaked template catalog by section/category/name), "add" (copy a template by name, or author one from explicit files), "update" (patch one set — named fields only; files replaces the whole pool), "remove" (one set, or "all"). Defaults to the ACTIVE scene when no sceneIdentifier is given. Out-of-range numbers are CLAMPED to the module's limits and the clamp is reported, not applied silently. Audio paths are HEAD-checked: a 404 is kept and warned about (a track has no sensible substitute). Sets are inert data without the module, so this WARNS when it is missing or disabled instead of reporting a working soundscape. GM-only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoSet name. Required when adding from `files`; optional rename on update.
filesNoData-relative audio paths making up the pool (what upload-asset returns). On UPDATE this REPLACES the whole pool. A path that does not resolve is kept and warned about, never swapped.
limitNoaction "library": maximum templates to return (default 40).
queryNoaction "library": match on template name, category, or section (e.g. "tavern").
actionYeslist = the scene's sound sets (with what would be playing right now); library = browse the prebaked template catalog; add/update/remove = author them.
activeNoWhether the set runs at all (default true).
volumeNoSet volume 0–1 (default 0.8), under the Ambient channel.
sectionNoRestrict to one section. Interval Sounds = randomized one-shots; Ambient Loops = continuous beds. Filters action "library", and narrows which `template` action "add" resolves when one name exists in both sections.
categoryNoRestrict to a category (substring match, e.g. "Forest"). Filters action "library", and narrows `template` resolution on action "add".
intervalNoInterval sets: seconds of silence between one-shots (1–3600, default 25).
templateNoaction "add": copy this LIBRARY template (its exact name, from action "library") — files, play style, and timing all come along. Any other field passed alongside overrides the template's value. A handful of names exist in BOTH sections, so pair this with `section` when the name is ambiguous. Omit to author a set from explicit `files` instead.
crossfadeNoLoop sets: overlap between members in seconds (0.5–30, default 4).
playStyleNointerval = a random file, then `interval ± intervalVariation` seconds of silence. loop = a continuous bed, members overlapped under a crossfade. Default interval.
whenToPlayNoDarkness gate, re-evaluated live: day = scene darkness < 0.5, night = ≥ 0.5 (default always).
verifyFilesNoaction "list": HEAD-check every pool file and report the missing ones. Off by default because it costs one request per file — turn it on when a set is silent and you want to know why.
setIdentifierNoWhich set to update/remove — its id or exact name (ids come from action "list"; a name that matches two sets is an error, not a coin flip). On "remove", the literal "all" clears every set from the scene.
pitchVariationNoPer-play pitch jitter in OCTAVES, 0–1 (default 0). 0.1 is a subtle, natural wobble.
sceneIdentifierNoScene id or exact name. STRICT — no fuzzy matching. Omit to target the ACTIVE scene. Ignored by action "library" (the catalog is world-wide).
volumeVariationNoPer-play volume jitter 0–1, attenuate-only — never louder than `volume` (default 0).
intervalVariationNoInterval sets: ± jitter on the silence, in seconds (default 5). Clamped to never exceed `interval`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.1.3

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations present, the description carries the full burden and delivers: out-of-range values are CLAMPED and reported, audio paths are HEAD-checked with 404s kept and warned about, and missing/disabled modules produce a warning instead of a fake success. It also discloses that updates replace whole pools on `files`, that `remove` accepts 'all', and that the tool is GM-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place; it is front-loaded with the core purpose and module context, then moves compactly through actions and behavioral caveats. For a 20-parameter tool with no annotations, this density is appropriate and well organized.

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?

Given the tool's complexity, full schema coverage, and no output schema, the description is complete enough: it covers all five actions, default scene selection, clamping, file verification behavior, module-dependency warning behavior, and key edge cases. An agent has what it needs to invoke the tool correctly and interpret non-2xx outcomes.

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?

The input schema already documents every parameter at 100% coverage, so the baseline is 3. The description adds real value on top by explaining action-specific behavior ('update' patches named fields only while `files` replaces the whole pool, 'remove' takes one set or 'all'), clarifying template-name ambiguity via `section`, and warning that a duplicate set name is an error. It doesn't materially change parameter meaning beyond that, though the cross-parameter guidance is strong.

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 opens with a specific verb and resource — 'Author a scene's atmospheric SOUND SETS' — and immediately explains the module's niche: randomized pools of small audio files with silence, or crossfaded beds. It distinguishes itself from AmbientSound placeables and Playlists, so an agent can tell it apart from sibling sounds tools without inspecting schemas.

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?

It states exactly when this tool is the right choice: core Foundry cannot do pools with silence or crossfaded beds, and explicitly rules out single-file positional AmbientSound placeables and Playlists as non-covering alternatives. It also gives operational conditions such as defaulting to the ACTIVE scene, strict scene identifiers, and GM-only access.

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