Skip to main content
Glama
Niclasp1501

ninjos-foundry-mcp

by Niclasp1501
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Manage playlists

manage-playlists
Destructive

Create, update, delete, or describe playlists in Foundry VTT, handling tracks, settings, and permission checks.

Instructions

Describe, create, update or delete playlists. describe without playlist lists every playlist (like list-playlists); with playlist it returns that one with its tracks, and a unique part of the name is enough there. create checks every track first and creates the playlist with all tracks in one step. update changes fields of the playlist and of existing tracks; adding or removing tracks is not part of it. delete works by playlist id only, is refused while a scene still uses the playlist, and needs the playlist permission "create, change and delete". For changes a playlist is found by id or exact name (case ignored when unique), never by a part of the name.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fadeNoCrossfade in milliseconds.
modeNo-1 disabled, 0 in order, 1 shuffled, 2 all at once (ambience).
nameNoName of the new playlist (create, required) or the new name (update).
colorNoColour as text, or null. When Foundry does not keep it, the result says so.
actionYesWhat to do.
folderNoId of a playlist folder, or null for the top level. A name is not accepted.
soundsNoTracks to create, or to change with update.
channelNoAudio channel of the playlist.
sortingNo"a" alphabetical, "m" manual.
updatesNoMore playlist fields for update. A parameter of the same name wins; known fields are checked alike.
playlistNoId or name for describe and update, id for delete. Null with describe lists all.
descriptionNoDescription of the playlist.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv14.2609.4

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the destructiveHint annotation, the description discloses that delete is refused while a scene uses the playlist, requires the permission 'create, change and delete', and that create validates every track before creating. It also explains naming rules (partial name for describe, exact/unique for changes, never partial for changes), adding valuable behavioral detail not captured by 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 a single dense paragraph but each sentence carries distinct, non-redundant information. It front-loads the action summary and then expands per action. While it could benefit from bullet points, there is no filler or wasted wording.

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 a complex tool with 12 parameters, nested objects, and no output schema, the description covers action behavior, name matching, permissions, and limitations. It mentions describe's return content (playlist with tracks) but does not specify return values for create/update/delete. Overall it is adequate and mostly complete.

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 baseline is 3. The description adds extra meaning: describe accepts a unique partial playlist name, while update/delete require exact name or id, and it clarifies that update does not add/remove tracks, which informs how the 'sounds' parameter should be used. This goes beyond the schema's parameter descriptions.

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 clearly states four specific actions (describe, create, update, delete) and the resource (playlists). It explicitly links describe-without-playlist to the sibling list-playlists, distinguishing the two tools. The action enum in the schema confirms the same verbs.

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 description names list-playlists as an alternative for listing all playlists and explicitly states what update does not do ('adding or removing tracks is not part of it'). It gives precise conditions for delete (id only, refused while a scene uses the playlist, permission required), providing clear when and when-not guidance.

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