Allows browsing and playing music from Spotify through Lyrion Music Server, including searching, browsing app menus, and playing tracks.
Allows browsing and playing music from TIDAL through Lyrion Music Server, including searching, browsing app menus, and playing tracks.
Allows searching and playing radio stations and podcasts from TuneIn through Lyrion Music Server, including searching and playing radio items.
Allows browsing and playing content from YouTube through Lyrion Music Server, including searching, browsing app menus, and playing tracks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@lms-mcp search for albums by Pink Floyd"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides LLM tools with access to the Lyrion Music Server (LMS) via its JSONRPC API.
Related MCP server: Spotify MCP Server
This MCP server provides the following tools for interacting with your Lyrion Music Server:
get_players: List all available players
get_player_status: Get detailed status of a specific player
test_connection: Test connection to the LMS server
play_pause: Toggle play/pause for a player
set_volume: Set player volume (0-100)
seek: Seek to a specific position in the current track
play_track: Play a specific track by ID
set_power: Turn a player on, off, or toggle power
set_sleep_timer: Set a sleep timer on a player
set_bass: Set bass level (-100 to 100)
set_treble: Set treble level (-100 to 100)
set_balance: Set left/right balance (-100 to 100)
set_loudness: Enable or disable loudness compensation
set_mute: Mute or unmute a player
playlist_action: Perform playlist actions (play, pause, stop, next, previous, shuffle, repeat)
get_current_playlist: Get the current playlist for a player
add_to_playlist: Add a track to the current playlist
clear_playlist: Clear the current playlist
jump_to_playlist_index: Jump to a specific track index
delete_playlist_item: Delete a track from the current playlist
move_playlist_item: Move a track within the current playlist
save_playlist: Save the current playlist with a name
delete_saved_playlist: Delete a saved playlist
rename_saved_playlist: Rename a saved playlist
set_shuffle: Set shuffle mode (off, song, album)
set_repeat: Set repeat mode (off, song, all)
get_server_status: Get LMS server status and library statistics
rescan_library: Trigger a library rescan (progressive or full)
set_random_play: Start or stop a random play mix (tracks, albums, artists, year)
get_years: Get years available in the library
get_decades: Get decades available in the library
get_new_music: Get recently added albums
get_random_albums: Get a random selection of albums
search_tracks: Search for tracks
search_artists: Search for artists
search_albums: Search for albums
get_playlists: Get all available playlists
get_genres: Get all genres available in the music database
search_tracks_by_genre: Search for tracks by genre
play_url: Play a direct URL or stream (internet radio, podcast, etc.)
add_url_to_playlist: Add a direct URL or stream to the current playlist
get_favorites: Get all favorites (often includes radio stations and online streams)
add_favorite: Add a URL or stream to favorites
play_favorite: Play a favorite by item ID
get_radios: Get radio directory categories and apps (TuneIn, etc.)
search_radio: Search TuneIn radio stations and podcasts
play_radio_item: Play a TuneIn radio search result by item ID
get_apps: Get installed online music apps (TIDAL, Spotify, Qobuz, YouTube, etc.)
browse_app: Browse an online music app menu
search_app: Search within an online music app
play_app_item: Play an item from an online music app by item ID
Clone this repository:
git clone <repository-url>
cd lms-mcpInstall dependencies:
npm installBuild the project:
npm run buildCopy the example environment file:
cp env.example .envEdit .env with your LMS server settings:
# Lyrion Music Server Configuration
LMS_HOST=localhost
LMS_PORT=9000
LMS_PROTOCOL=http
LMS_TIMEOUT=10000LMS_HOST: IP address or hostname of your LMS server (default: localhost)
LMS_PORT: Port number of your LMS server (default: 9000)
LMS_PROTOCOL: Protocol to use (http or https, default: http)
LMS_TIMEOUT: Request timeout in milliseconds (default: 10000)
# Development mode
npm run dev
# Production mode
npm start
# Watch mode for development
npm run watchAdd the following to your Claude Desktop configuration file:
{
"mcpServers": {
"lms": {
"command": "node",
"args": ["/path/to/lms-mcp/dist/index.js"],
"env": {
"LMS_HOST": "your-lms-server-ip",
"LMS_PORT": "9000"
}
}
}
}The server communicates via stdio using the Model Context Protocol. Any MCP-compatible client can connect to it.
Returns a list of all available players.
Parameters: None
Returns: Array of player objects with properties like playerid, name, model, ip, etc.
Get detailed status of a specific player.
Parameters:
playerId (string): The ID of the player to get status for
Returns: Player status object with current track, volume, playback state, etc.
Test the connection to the LMS server.
Parameters: None
Returns: Connection status message
Toggle play/pause for a player.
Parameters:
playerId (string): The ID of the player to control
Set the volume of a player.
Parameters:
playerId (string): The ID of the player to control
volume (number): Volume level (0-100)
Seek to a specific position in the current track.
Parameters:
playerId (string): The ID of the player to control
position (number): Position in seconds to seek to
Play a specific track by ID.
Parameters:
playerId (string): The ID of the player to control
trackId (string): The ID of the track to play
Perform various playlist actions.
Parameters:
playerId (string): The ID of the player to control
action (string): Action to perform (play, pause, stop, next, previous, shuffle, repeat)
Get the current playlist for a player with complete track information.
Parameters:
playerId (string): The ID of the player to get playlist for
Returns: Object containing:
tracks: Array of track objects with complete metadata (artist, title, album, duration, etc.)
currentTrack: Index of the currently playing track
totalTracks: Total number of tracks in the playlist
visibleTracks: Number of tracks visible in the current view
Add a track to the current playlist.
Parameters:
playerId (string): The ID of the player to add track to
trackId (string): The ID of the track to add
Clear the current playlist.
Parameters:
playerId (string): The ID of the player to clear playlist for
Search for tracks in your music library.
Parameters:
query (string): Search query
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of track objects matching the search query
Search for artists in your music library.
Parameters:
query (string): Search query
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of artist objects matching the search query
Search for albums in your music library.
Parameters:
query (string): Search query
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of album objects matching the search query
Get all available playlists.
Parameters: None
Returns: Array of playlist objects
Get all genres available in the music database.
Parameters: None
Returns: Array of genre objects with genre name, ID, and favorites URL
Search for tracks by genre.
Parameters:
genre (string): Genre name to search for
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of track objects with complete metadata (artist, title, album, duration, etc.)
Play a direct URL or stream on a player.
Parameters:
playerId (string): Player ID to control
url (string): URL or stream to play
Add a direct URL or stream to the current playlist.
Parameters:
playerId (string): Player ID to add URL to
url (string): URL or stream to add
Get all favorites. Favorites often include radio stations, online streams, and playlists.
Parameters:
limit (number, optional): Maximum number of results (default: 100)
Returns: Array of favorite item objects with id, name, type, url, image, etc.
Add a URL or stream to favorites.
Parameters:
url (string): URL or stream to add
title (string): Title for the favorite
Play a favorite by item ID on a player.
Parameters:
playerId (string): Player ID to play favorite on
itemId (string): Favorite item ID (the id field from get_favorites)
Get radio directory categories and apps (TuneIn, etc.).
Parameters:
limit (number, optional): Maximum number of results (default: 100)
Returns: Array of radio category/app objects with cmd, name, type, icon, etc.
Search TuneIn radio stations and podcasts.
Parameters:
playerId (string): Player ID to use for searching (TuneIn search requires a real player)
query (string): Search query
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of radio search result objects
Play a TuneIn radio search result by item ID on a player.
Parameters:
playerId (string): Player ID to play radio on
itemId (string): Radio item ID (the id field from search_radio)
Get installed online music apps such as TIDAL, Spotify (Spotty), Qobuz, YouTube, SoundCloud, Mixcloud, and Podcasts.
Parameters:
limit (number, optional): Maximum number of results (default: 100)
Returns: Array of app objects with cmd, name, type, icon, etc. Use the cmd value with browse_app and search_app.
Browse an online music app menu.
Parameters:
playerId (string): Player ID to use for browsing
appCmd (string): App command name (the cmd field from get_apps, e.g. tidal, spotty, qobuz)
itemId (string, optional): Menu item ID to browse into (omit for top-level menu)
limit (number, optional): Maximum number of results (default: 50)
Returns: Object with title, count, and items array. Items have id, name, type, image, isaudio, and hasitems.
Search within an online music app.
Parameters:
playerId (string): Player ID to use for searching
appCmd (string): App command name (e.g. tidal, spotty, qobuz)
query (string): Search query
searchItemId (string): Search category item ID (e.g. after browsing the TIDAL Search menu, albums might be item 7.3)
limit (number, optional): Maximum number of results (default: 50)
Returns: Object with title, count, and items array.
Play an item from an online music app by item ID.
Parameters:
playerId (string): Player ID to play on
appCmd (string): App command name (e.g. tidal, spotty, qobuz)
itemId (string): Item ID to play (the id field from browse_app or search_app)
Turn a player on, off, or toggle power.
Parameters:
playerId (string): Player ID to control
state (string): on, off, or toggle
Set a sleep timer on a player in seconds.
Parameters:
playerId (string): Player ID to control
seconds (number): Sleep timer in seconds (0 to cancel)
Set bass level on a player.
Parameters:
playerId (string): Player ID to control
level (number): Bass level from -100 to 100
Set treble level on a player.
Parameters:
playerId (string): Player ID to control
level (number): Treble level from -100 to 100
Set left/right balance on a player.
Parameters:
playerId (string): Player ID to control
level (number): Balance from -100 (left) to 100 (right)
Enable or disable loudness compensation.
Parameters:
playerId (string): Player ID to control
enabled (boolean): true to enable, false to disable
Mute or unmute a player.
Parameters:
playerId (string): Player ID to control
muted (boolean): true to mute, false to unmute
Jump to a specific track index in the current playlist.
Parameters:
playerId (string): Player ID to control
index (number): Track index to jump to (0-based)
Delete a track from the current playlist by index.
Parameters:
playerId (string): Player ID to control
index (number): Track index to delete (0-based)
Move a track within the current playlist.
Parameters:
playerId (string): Player ID to control
fromIndex (number): Source track index
toIndex (number): Destination track index
Save the current player playlist as a named playlist.
Parameters:
playerId (string): Player ID whose current playlist to save
name (string): Name for the saved playlist
Delete a saved playlist.
Parameters:
playlistId (string): Saved playlist ID (the id field from get_playlists)
Rename a saved playlist.
Parameters:
playlistId (string): Saved playlist ID
name (string): New name for the playlist
Set shuffle mode on a player.
Parameters:
playerId (string): Player ID to control
mode (string): off, song, or album
Set repeat mode on a player.
Parameters:
playerId (string): Player ID to control
mode (string): off, song, or all
Start or stop a random play mix.
Parameters:
mode (string): tracks, albums, artists, or year
enabled (boolean): true to start, false to stop
Get LMS server status and library statistics (version, total albums/artists/songs, last scan, etc.).
Parameters: None
Returns: Server status object
Trigger a library rescan.
Parameters:
mode (string, optional): progressive (scan for changes) or full (wipe cache and rescan), default progressive
Get years available in the music library.
Parameters:
limit (number, optional): Maximum number of results (default: 100)
Returns: Array of year objects
Get decades available in the music library.
Parameters:
limit (number, optional): Maximum number of results (default: 100)
Returns: Array of decade objects
Get recently added albums.
Parameters:
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of album objects
Get a random selection of albums.
Parameters:
limit (number, optional): Maximum number of results (default: 50)
Returns: Array of album objects
src/
├── index.ts # Main entry point
├── mcp-server.ts # MCP server implementation
├── lms-client.ts # LMS JSONRPC client
├── types.ts # TypeScript type definitions
└── config.ts # Configuration managementnpm run buildnpm run devnpm run watchVerify your LMS server is running and accessible
Check the LMS_HOST and LMS_PORT configuration
Test the connection using the test_connection tool
Ensure your LMS server allows JSONRPC requests
"LMS request failed": Check network connectivity and LMS server status
"Invalid player ID": Use get_players to see available player IDs
"Unknown tool": Ensure you're using the correct tool names from the API reference
This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for details.
Contributions are welcome! Please feel free to submit a Pull Request.
Add a URL or stream to favorites
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL or stream to add to favorites | |
| title | Yes | Title for the favorite |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint false), indicating a mutation. However, it does not add extra behavioral details like idempotency or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple operation, the description is adequate but could include hints about what 'favorites' are or how to manage them, especially given the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the description adds no new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add' and the resource 'favorites', and distinguishes from sibling tools like play_favorite and add_to_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as add_to_playlist or play_favorite. The description lacks context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a track to the current playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to add track to | |
| trackId | Yes | Track ID to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false). The description adds no behavioral details beyond the action itself, such as whether tracks are appended or replaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, the phrasing 'current playlist' is slightly ambiguous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal but adequate for a simple tool with two well-documented parameters. Lacks context on playlist selection and effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions for both parameters. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and resource (track to playlist). However, 'current playlist' is ambiguous without context about how 'current' is determined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs siblings like add_url_to_playlist or add_favorite, and no prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a direct URL or stream to the current playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to add URL to | |
| url | Yes | URL or stream to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false), and the description says 'Add', which is consistent. However, it does not disclose behavior like whether duplicate URLs are allowed, error handling, or the position where items are added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous words. Front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description is minimally adequate. It does not explain the effect on the playlist (e.g., append position) or potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds no extra meaning beyond 'URL or stream' vs the schema's 'URL or stream to add'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add', the resource 'direct URL or stream', and the target 'current playlist', distinguishing it from siblings like play_url or add_favorite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like play_url or add_to_playlist. It assumes a current playlist exists but does not mention preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse an online music app menu (TIDAL, Spotify, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to use for browsing | |
| appCmd | Yes | App command name (the "cmd" field from get_apps, e.g. "tidal", "spotty", "qobuz") | |
| itemId | No | Optional menu item ID to browse into (omit for top-level menu) | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the readonly nature is covered. The description adds no further behavioral context (e.g., whether browsing is session-affecting, how long it takes). With annotations present, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with purpose, no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not hint at what the response looks like (e.g., a list of menu items or sub-menus). For a tool with 4 parameters, additional detail about the return format or navigation would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds value by mapping appCmd to the 'cmd' field from get_apps, but beyond that, it doesn't clarify the meaning of itemId or limit beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (browse) and resource (online music app menu), and the parenthetical examples distinguish it from sibling tools like search_app or play_app_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives such as search_app (for searching) or play_app_item (for playing). The description implies browsing an app menu, but it doesn't specify that get_apps should be used first to obtain appCmd values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the current playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to clear playlist for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description 'Clear' implies destructiveness, which aligns with the destructiveHint annotation. However, it adds no additional behavioral context beyond the annotation. No mention of irreversibility, effect on other players, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and to the point. However, for a tool with sibling complexity, slightly more detail could be warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema) and annotations present, the description is minimally sufficient. It defines the action but lacks details on what 'clearing' entails (e.g., does it maintain the playlist object?). Not fully complete for an agent to understand behavior without assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'playerId' is fully described in the schema with 'Player ID to clear playlist for'. The description adds no extra meaning. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Clear the current playlist' uses a clear verb+resource format. It conveys the action of removing all items from a playlist, distinguishing it from siblings like 'delete_playlist_item' (removes one item) and 'delete_saved_playlist' (removes the playlist itself). However, it does not explicitly say it empties rather than deletes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'delete_playlist_item' or 'delete_saved_playlist'. No prerequisites or context provided. The description lacks any hint of usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a track from the current playlist by index
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| index | Yes | Track index to delete (0-based) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, which matches the 'Delete' action. The description adds context about 'current playlist', but does not disclose error behavior or permissions. Beyond annotations, the additional value is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 8 words with no filler. Perfectly sized for conveying the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with full schema annotations, the description is mostly complete. It lacks mention of reindexing behavior or error cases, but output schema is absent, so agent may need to infer from context. Still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond 'by index', which is already in the schema. It does not elaborate on playerId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a track from the current playlist by index', using a specific verb and resource. It distinguishes from siblings like clear_playlist (delete all) and delete_saved_playlist (delete playlist itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing a single track by index, but does not explicitly contrast with alternatives like clear_playlist or move_playlist_item. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playlistId | Yes | Saved playlist ID (the "id" field from get_playlists) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's "Delete" is consistent. However, it doesn't disclose reversibility, confirmation requirements, or permission needs, which are relevant for destructive actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no unnecessary words. Every word earns its place, providing the essential information concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and a destructive annotation, the description is nearly complete. It could mention permanence, but it's sufficient given the annotations and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a clear description for playlistId. The tool description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description "Delete a saved playlist" clearly states the verb (Delete) and the resource (saved playlist), distinguishing it from siblings like clear_playlist (which removes items but keeps the playlist) and delete_playlist_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided. The description is adequate for a straightforward deletion but lacks guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get installed online music apps (TIDAL, Spotify, Qobuz, YouTube, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds value by listing examples of apps, but does not disclose additional behavioral traits such as authentication requirements or empty result behavior. Given annotation coverage, the description provides adequate but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the tool's purpose effectively without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and no output schema, the description adequately explains what the tool does and provides examples. It is mostly complete, though it could mention that it returns an array of app objects, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'limit'. The description does not add any new meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get installed online music apps' with specific examples (TIDAL, Spotify, Qobuz, YouTube), making the verb and resource explicit. It distinguishes from sibling tools like get_playlists or get_favorites by focusing on music streaming services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use this tool: to list installed music apps. While it provides clear context, it does not explicitly state when not to use it or mention alternatives among the many sibling getter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current playlist for a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to get playlist for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds no new behavioral context beyond that. It does not disclose whether the result may be empty, whether the player must be active, or any other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words. It conveys the essential information without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one param, read-only, no output schema), the description is minimally adequate. However, it could improve by clarifying what 'current playlist' means in context (e.g., the playlist currently playing or selected for the player).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the parameter, so the description adds no additional meaning. The baseline score of 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'current playlist', and the context 'for a player'. It effectively distinguishes from sibling tools like 'get_playlists' which returns all playlists, and 'get_player_status' which returns player state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not explain that it retrieves the currently active/playing playlist for a specific player, nor does it mention scenarios where it might return nothing (e.g., if no playlist is active).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get decades available in the music library
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no further behavioral details (e.g., return format, sorting, or any side effects). Since annotations cover the safety profile, a 3 is appropriate as the description adds marginal value beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is perfectly concise and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with one optional parameter and no output schema, the description is mostly complete. It could mention the output format or sorting order, but the information provided is sufficient for an agent to understand the tool's basic function. The presence of readOnlyHint reduces the need for extensive behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'limit' parameter, which already includes a default value and brief description. The tool description does not add any additional information about the parameter, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'decades available in the music library', making the purpose obvious. However, it does not explicitly distinguish from sibling tools like 'get_years', which could cause confusion in selection, though the distinct resource name provides implicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'get_years' is provided. The description simply states what it does, leaving the agent to infer usage context without any exclusions or recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all favorites (often includes radio stations and online streams)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so description doesn't need to reiterate safety. It adds behavioral context by noting the inclusion of radio stations and streams, but doesn't discuss pagination or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, the description is adequate. It could elaborate on what constitutes a 'favorite', but the sibling list is large and the description serves its purpose without being overly verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with description and default for 'limit'. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get' and resource 'favorites', and adds context that it often includes radio stations and online streams, distinguishing it from siblings like get_radios and get_playlists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_radios or get_playlists. The mention of 'often includes radio stations and online streams' provides implicit context but lacks direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all genres available in the music database
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the description does not need to restate safety. The description adds no behavioral context beyond the annotation, such as pagination or response format. For a tool with no parameters, 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple listing operation with no parameters and a clear annotation, the description is sufficient. It lacks details about the return format, but for such a straightforward tool, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and is fully covered (100%). The description adds no parameter info because there are none. According to the rule, 0 parameters gives a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'all genres available in the music database'. While it does not explicitly distinguish from sibling tools like 'search_tracks_by_genre', the names alone imply different purposes. The description is specific enough to identify the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. Since it is a simple retrieval tool, the context implicitly suggests it is for fetching all genres, but no when-not-to-use or sibling comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recently added albums
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds 'recently added' as behavioral context, but lacks details like sorting order, time window, or response format. With annotation coverage, the description provides minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words), directly front-loaded with the purpose. It could benefit from slightly more detail, but it is succinct without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one optional parameter and no output schema, the description is minimally adequate. It tells the agent what the tool does but lacks context on ordering, pagination, or what constitutes 'recently added'. Somewhat incomplete but functional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'limit' parameter, which is well-described in the schema. The description does not mention the parameter, so it adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recently added albums, which is specific and informative. However, it does not differentiate from sibling tools like get_random_albums or search_albums, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives such as search_albums or get_favorites. No context about usage or exclusions is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available players from the LMS server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's behavioral burden is lowered. The description adds no extra behavioral context beyond what the annotation implies (e.g., no mention of performance, resource impact, or return format). It is consistent but does not enrich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, short sentence that conveys the entire purpose without any wasted words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless retrieval tool, the description is nearly complete. It lacks details about what the returned players contain (e.g., IDs, names), but given the absence of an output schema, the description still serves its primary goal of identifying what the tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the description states 'all available players', which clarifies the scope. With no parameters and 100% schema coverage, the description adds sufficient meaning—it confirms no filtering is possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Get) and the resource (all available players from the LMS server). The verb+resource combination is specific and distinct from sibling tools like get_player_status or sync_players, which imply different scopes or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. However, the tool's simplicity (no parameters, retrieving all players) makes its usage obvious. It implicitly contrasts with siblings that operate on specific players, but no alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current status of a specific player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to get status for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds no additional behavioral context beyond the parameter. No mention of return format or scope of 'status'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of what 'status' entails (e.g., connectivity, playback state). For a tool with one parameter, more detail would help an agent understand the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description for playerId. Description adds no further meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'current status of a specific player', distinguishing it from sibling tools like get_players (list all) and get_server_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like get_players. Implied by parameter requirement but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available playlists
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the readOnlyHint annotation. It does not explain what 'available' means, whether the list includes user-created playlists, system playlists, or both, or any ordering or filtering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It is front-loaded with the core action. However, it is somewhat terse and could include minimal clarifying context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters, the description is minimally viable. It lacks detail on the context of 'available playlists', but given the tool's simplicity and presence of annotations, it is adequate with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema description coverage is 100%. The description does not need to add parameter semantics, so a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all available playlists', which clearly indicates the action (get) and resource (playlists). It distinguishes from sibling tools like get_current_playlist by specifying 'all available'. However, 'available' is vague and could be clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_current_playlist or save_playlist. The description lacks any context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get radio directory categories and apps (TuneIn, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's read nature is consistent but adds no additional behavioral context (e.g., pagination, ordering, side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded with verb. Could be slightly more informative without verbosity, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should explain return values. It mentions categories and apps but not structure. Adequate for a simple tool, but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (limit). The description does not mention the parameter, so it adds no meaning beyond the schema. Baseline 3 per rules for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves radio directory categories and apps, with an example (TuneIn). It uses a specific verb and resource, distinguishing it from siblings like 'get_apps' and 'get_genres'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings (e.g., browse_app, search_radio). The description lacks when-not-to-use and alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a random selection of albums
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior (readOnlyHint: true). The description adds 'random selection' as a behavioral trait, but does not disclose details like randomness guarantees, potential duplicates, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (5 words), containing no filler. However, it is slightly under-specified for a standalone description, earning a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional parameter, no output schema), the description is minimally adequate. It does not explain return format or behavioral guarantees, but is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the limit parameter with a description. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a random selection of albums', which is specific and distinguishes it from siblings like 'search_albums' that likely filter by criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., search_albums for targeted queries). The description does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get LMS server status and library statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's addition of 'status and statistics' is consistent but adds little behavioral context beyond what is inferred from the name and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that directly conveys the tool's purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple parameterless tool but does not elaborate on what specific library statistics are returned or the format of the response. Since there is no output schema, some additional detail could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. The description adds no parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves LMS server status and library statistics. It is distinct from sibling tools like get_player_status, which focus on players.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Usage is implied: call this to get server-level info, not player-specific. No alternatives are mentioned, but the name and context make it somewhat clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all synchronization groups
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the readOnlyHint annotation, which already indicates a safe read operation. While consistent, the description does not disclose any additional traits like what synchronization groups are or the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. It could be slightly more informative without losing conciseness, but it earns its place by stating the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and minimal complexity, the description is adequate but not complete. The term 'synchronization groups' is undefined, and there is no context about what the tool returns or its role among many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100%. The description does not need to add parameter meaning. Baseline score of 4 is appropriate as the description is adequate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all synchronization groups' clearly states the verb 'Get' and the resource 'synchronization groups'. It is specific and not a tautology, but it does not differentiate from sibling tools like get_players or get_server_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get synchronization status for a specific player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to get sync status for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation, indicating a read operation. However, it adds no behavioral details beyond what the annotation already provides, such as whether status is real-time or cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded and directly conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is sufficient. However, it could hint at what the status contains (e.g., last sync time) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a clear parameter description. The tool description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and resource (synchronization status for a specific player), making the purpose well-defined. However, it does not differentiate from sibling tools like get_sync_groups or get_player_status, which could be confused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_sync_groups, sync_players). The description lacks any context about prerequisites or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get years available in the music library
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds no additional behavioral context. It does not describe sorting, filtering, or data format beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Perfectly concise for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity and no output schema, the description is somewhat adequate but could mention return format or default behavior. Missing detail on what 'years' includes (e.g., range, sorted).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'limit' with description and default. The description adds no extra meaning about the parameter or the result set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get years available in the music library', using a specific verb and resource. It distinguishes from siblings like 'get_decades' which retrieves decades instead of years.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_decades). The description is minimal and does not provide context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Jump to a specific track index in the current playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| index | Yes | Track index to jump to (0-based) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks details on the behavioral impact beyond the fact it is not read-only (as indicated by annotations). It does not specify whether playback starts, if the playlist state changes, or any side effects, leaving ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description should clarify the effect of jumping (e.g., whether it starts playing or just selects). It fails to provide sufficient context for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'playerId' and 'index' described in the schema. The description adds no additional meaning or constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('jump') and the resource ('specific track index in the current playlist'). It effectively distinguishes from sibling tools like 'play_track' (which uses track ID) or 'seek' (which seeks within the current track).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'play_track' or 'seek'. The description simply states the action without context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a track within the current playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| fromIndex | Yes | Source track index | |
| toIndex | Yes | Destination track index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, description adds 'move' confirming mutation. However, no details on reversibility, index bounds, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words; highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple move operation, but lacks explanations of return values, error handling, or index constraints. Could be more complete given 3 required params and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds no additional meaning beyond parameter descriptions already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'move', resource 'track within the current playlist', and scope. Distinguishes from sibling tools like delete_playlist_item or add_to_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., playlist must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play an item from an online music app by item ID
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to play on | |
| appCmd | Yes | App command name (e.g. "tidal", "spotty", "qobuz") | |
| itemId | Yes | Item ID to play (the "id" field from browse_app or search_app) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation). Description says 'Play' confirming mutation but adds no details on behavior (e.g., whether it replaces current queue, error handling if player is off). Minimal incremental value over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear subject and object. No redundancy, but could be slightly more structured with if-then context. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 required parameters, no output schema, and many sibling tools, the description is insufficient. It lacks information on what 'play' entails (start immediately? add to queue?), prerequisites (player must be on?), and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The tool description adds 'by item ID', aligning with the itemId param, but does not provide new meaning beyond what's in the schema. Baseline score for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Play', resource 'item from an online music app', and the key parameter 'item ID'. It effectively distinguishes from siblings like play_track (local) or play_favorite by specifying the source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like play_track or play_favorite. The description implies that the item ID comes from browse_app or search_app but does not state when to choose this over other play tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play a favorite by item ID on a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to play favorite on | |
| itemId | Yes | Favorite item ID (the "id" field from get_favorites) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'play' which implies a state change, and the annotation readOnlyHint=false confirms it is not read-only. However, no additional behavioral details are given (e.g., whether playback replaces current, if player must be online, or return value).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently captures the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description is adequate. It explains the core functionality, though a bit more context about the result (e.g., 'starts playback') would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with inline descriptions for both parameters. The tool description adds no extra meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (play), the resource (favorite), and the context (on a player by item ID). However, it does not explicitly differentiate from sibling tools like play_app_item or play_track, but the term 'favorite' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., play_track, play_app_item). The description does not mention prerequisites like having retrieved favorites via get_favorites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform playlist actions (play, pause, stop, next, previous, shuffle, repeat)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| action | Yes | Playlist action to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies mutation (perform actions), consistent with readOnlyHint=false. No additional behavioral details are provided beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It could be slightly improved by front-loading the purpose, but it remains concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and many sibling tools, the description is too minimal. It does not explain that the tool controls the current playlist or its effects on playback state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions in the schema. The tool description does not add extra meaning or constraints beyond what is already available.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'perform' and the resource 'playlist actions' with a list of specific actions. However, it does not distinguish itself from sibling tools like play_pause or set_shuffle, which may overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as play_pause, set_shuffle, or set_repeat. The description lacks context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play or pause a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control (use "0" for all players) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive action (readOnlyHint=false). Description adds no additional behavioral context such as error handling, per-player state assumptions, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that states the purpose efficiently. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter toggle tool, the description covers the core purpose. However, it does not explain return values (no output schema) or confirm whether it toggles vs. requires a play/pause command. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value to the parameter by clarifying that '0' controls all players, which is not in the schema's parameter description. Schema coverage is 100%, so the baseline is 3; the added clarification lifts it to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'play or pause' and the resource 'player', distinguishing it from more specific actions like play_track or set_power. However, it could be more precise by specifying that it toggles the state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like play_track, set_power, or seek. It does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play a TuneIn radio search result by item ID on a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to play radio on | |
| itemId | Yes | Radio item ID (the "id" field from search_radio) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, consistent with the mutation implied by 'Play'. The description does not add extra behavioral details beyond the basic action, but this is acceptable given the simple nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description sufficiently captures the core functionality. It could be improved by noting that playing replaces the current stream, but it is generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with clear descriptions for both parameters. The description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Play' and the resource 'TuneIn radio search result', and specifies the key identifier 'by item ID' and target 'on a player'. It effectively distinguishes from sibling tools like 'play_favorite' or 'play_track'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'play_favorite' or 'play_url'. The description lacks prerequisites, constraints, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play a specific track by ID
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| trackId | Yes | Track ID to play |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the description's 'play' aligns with a mutation. However, no additional behavioral context is given, such as whether the track starts immediately or replaces the current queue.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it sacrifices completeness by omitting the playerId requirement. It is adequately structured but not as helpful as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with two required parameters and no output schema, the description should at least mention both parameters. It misses playerId, making it incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. But the description only mentions trackId by ID, failing to note the required playerId parameter, which could cause misuse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Play a specific track by ID', which clearly indicates the action and resource. However, it does not distinguish from sibling tools like play_app_item or play_favorite, which are similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives, such as play_url or play_radio_item. The agent is left to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play a direct URL or stream on a player (internet radio, podcast, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| url | Yes | URL or stream to play |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the action ('play') without revealing behavioral details beyond the annotation (readOnlyHint=false). It does not explain whether the stream replaces the current track, how errors are handled, or if any side effects occur (e.g., stopping other playbacks). The agent lacks critical context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately communicates the tool's core function. It contains no filler or redundancies. All words are meaningful and earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of full schema coverage, the description is adequate but not complete. It lacks context for when to choose this over siblings, and does not explain return values or behavior. A more complete description would include typical use cases and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters (playerId, url). The description adds no additional semantic meaning or constraints (e.g., supported URL formats, playerId resolution). Baseline score of 3 is appropriate as the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Play a direct URL or stream on a player'. It uses a specific verb (play) and resource (direct URL/stream), and distinguishes from sibling tools like play_radio_item or play_track which are for specific content types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the many other play-related siblings (e.g., play_app_item, play_favorite). It does not mention prerequisites, such as that a player must be started or that the URL must be accessible. The absence of usage context makes it hard for an AI agent to choose this correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a saved playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playlistId | Yes | Saved playlist ID | |
| name | Yes | New name for the playlist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly, so the description confirms mutation but adds no further behavioral details (e.g., side effects, authorization needs, or return value).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no wasted words, appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation, the description is adequate but lacks context on idempotency, constraints, or behavior (e.g., whether rename fails if name already exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Rename') and resource ('saved playlist'), effectively distinguishing it from siblings like 'delete_saved_playlist' or 'save_playlist'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any prerequisites or context (e.g., the playlist must already exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a library rescan
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Rescan mode (progressive = scan for changes, full = wipe cache and rescan) | progressive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, which covers the main behavioral trait. The description adds no extra detail beyond the schema's mode description (e.g., whether rescan interrupts playback or requires idle state).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Information is front-loaded and appropriately compact for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional param, no output schema), the description is nearly complete. However, it could briefly mention that it starts a background task, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any additional meaning to the 'mode' parameter beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb-resource pair ('Trigger a library rescan') that clearly identifies the action and target. No sibling tool has a similar function, so differentiation is inherent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, what conditions should be met before triggering, or any pre-requisites. The description is too terse to provide usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save the current player playlist as a named playlist
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID whose current playlist to save | |
| name | Yes | Name for the saved playlist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only. Description adds that it saves the 'current' playlist, but does not disclose potential overwriting behavior, permission needs, or side effects beyond the mutation implied by 'save'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no unnecessary words. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema, no enums), the description covers the essential purpose. Could potentially mention if saving with an existing name overwrites or errors, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description does not add any additional meaning beyond what the schema provides, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'save', resource 'current player playlist', and outcome 'as a named playlist'. Distinguishes it from sibling tools like delete_saved_playlist and rename_saved_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context (saving current playlist) but provides no explicit guidance on when to use this tool versus alternatives like add_to_playlist or clear_playlist. No exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for albums
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds no behavioral details beyond the purpose—such as whether the search is case-sensitive, supports partial matches, or returns paginated results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, the description is under-specified and does not effectively earn its space. It is essentially a tautology of the tool name, missing important context that could be conveyed in a few more words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should ideally describe the return format (e.g., list of album objects with properties). It also does not address the many sibling tools, leaving the agent without cues for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with descriptions for both parameters (query and limit). The description adds no extra meaning beyond what the schema already provides. The baseline of 3 is appropriate since the schema is self-sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and resource 'albums', making the core purpose obvious. However, it lacks any details about search behavior (e.g., field matching, sorting) that could help differentiate from sibling album-related tools like get_random_albums or get_new_music.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus sibling search tools (e.g., search_artists, search_tracks). The description does not specify that it is for albums only, nor does it mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search within an online music app (TIDAL, Spotify, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to use for searching | |
| appCmd | Yes | App command name (e.g. "tidal", "spotty", "qobuz") | |
| query | Yes | Search query | |
| searchItemId | Yes | Search category item ID (e.g. TIDAL search albums might be "7.3" after browsing the Search menu) | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description does not need to disclose read-only behavior. However, the description adds no further behavioral details such as rate limits, pagination, or result structure. It meets the baseline but adds little value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded and without redundancy. It could be slightly more detailed but remains concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and many sibling tools, the description is too minimal. It does not explain the return value format, pagination behavior, or the role of searchItemId. The tool's context is not fully covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions. The description does not add significant meaning beyond the schema; it merely repeats the context of 'online music app'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search within an online music app' and gives examples like TIDAL, Spotify. It distinguishes from sibling tools like search_albums or search_tracks, which are more specific searches for other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when searching within a specific app, but it does not explicitly state when to use this tool versus the other search siblings (e.g., search_albums, search_tracks). No when-not conditions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for artists
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but the description adds no additional behavioral context such as search behavior, sorting, or pagination. For a read operation, this is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but arguably too terse. It front-loads the purpose but omits potentially useful details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and minimal description, the tool lacks contextual completeness. It does not explain return format, search syntax, or behavior, which is insufficient for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description does not add any meaning beyond what the schema provides, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search for artists' clearly states the verb and resource, and distinguishes from sibling tools like search_albums and search_tracks. However, it lacks any additional context or scope beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as search_albums or search_tracks. There are no exclusions or contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search TuneIn radio stations and podcasts
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to use for searching (TuneIn search requires a real player) | |
| query | Yes | Search query | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation, confirming a read-only search behavior. However, it adds no additional context about rate limits, result format, or error conditions beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with no output schema, the description is sufficient. It covers the what and where (TuneIn), but could be improved by noting the return type or result structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage and documents all three parameters clearly. The description does not add further meaning beyond the schema, which is adequate for a high-coverage situation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and the resource ('TuneIn radio stations and podcasts'), making it easy to distinguish from sibling search tools like search_albums or search_tracks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching TuneIn content but does not explicitly contrast with alternatives or specify when to use this tool over others. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for tracks
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds no extra behavioral context (e.g., pagination, sorting), but also does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and to the point. However, it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool, the description is adequate but lacks details on return format or behavior. With no output schema, the description should clarify what the response contains, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents both parameters. The description adds no additional meaning beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search for tracks' clearly states the verb (Search) and the resource (tracks), distinguishing it from sibling search tools like search_albums and search_artists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With many sibling search tools, the description should provide context or when-not-to-use, but it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for tracks by genre
| Name | Required | Description | Default |
|---|---|---|---|
| genre | Yes | Genre name to search for | |
| limit | No | Maximum number of results (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. Description adds no extra behavioral context (e.g., side effects, speed, pagination). It is consistent but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 5-word sentence, concise and front-loaded. It earns its place but could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what the tool returns (e.g., list of tracks). It only states the action, leaving the agent to guess the output structure. Incomplete for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both genre and limit have descriptions). The tool description does not add parameter-level detail beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Search for tracks by genre' — a clear verb+resource+filter. It is distinguishable from sibling tools like search_tracks (generic text search) and search_albums (different resource). However, it lacks specifics like 'returns matching tracks with metadata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., search_tracks, search_albums). Does not mention that this filters by genre specifically, nor does it explain when to prefer it over general search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Seek to a specific position in the current track
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| position | Yes | Position in seconds to seek to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, consistent with mutation. Description adds no extra behavioral traits beyond seeking, such as what happens if position is out of bounds or if the player is paused. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no unnecessary words, front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 required params, no output schema, no nested objects), the description is nearly complete. It lacks mention of edge cases like invalid position, but is generally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description does not add meaning beyond schema, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'seek' and the resource 'specific position in the current track'. It is distinct from sibling tools like play_pause or set_volume, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use seek versus alternatives. For example, it does not mention that seek is used to jump to a specific time, while jump_to_playlist_index moves to a different track in the playlist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set left/right balance on a player (-100 to 100)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| level | Yes | Balance level (-100 = left, 100 = right) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, so the description's 'Set' is consistent. The description adds the valid range (-100 to 100), but does not disclose other behavioral traits like whether changes are immediate, reversible, or require the player to be active. With annotations, a score of 3 is appropriate – adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence that states the purpose and includes the valid range. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 required parameters, but the description does not mention what the response looks like or error conditions. Since there is no output schema, the description should provide some guidance on return values or side effects. This gap lowers completeness to a 3.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with full coverage. The tool description does not add any semantic information beyond what the schema provides (e.g., the level range is already in the parameter description). Therefore, per the rules, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Set left/right balance on a player') and includes the valid range (-100 to 100). It clearly distinguishes from sibling tools like set_bass, set_treble, set_volume, etc., which control different audio parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like set_bass, set_treble, etc. There is no mention of when not to use it or what prerequisites are needed (e.g., player must be playing). The agent would have to infer usage from the name and range.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set bass level on a player (-100 to 100)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| level | Yes | Bass level (-100 to 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, consistent with the description. No additional behavioral traits (e.g., effect on other settings) are disclosed beyond the range constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no extraneous text, includes essential range information in parentheses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with no output schema, the description and schema together adequately define the tool, though a note about return behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documents both parameters fully (100% coverage), so the description adds no extra semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('bass level on a player'), clearly distinguishes from sibling tools like set_treble or set_balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adjusting bass but does not explicitly state when to use this tool versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable loudness compensation on a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| enabled | Yes | Enable loudness |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description's statement about enabling/disabling is consistent but adds no additional behavioral details beyond that. It does not disclose side effects, permissions needed, or impact on other settings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise and directly states the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool with two fully documented parameters and no output schema, the description is minimally adequate. However, it lacks context about when to use it among many sibling settings tools, and does not explain return behavior or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% - both parameters have clear descriptions in the schema. The tool description adds no further parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: enabling or disabling loudness compensation on a player. The verb 'set' plus resource 'loudness' is precise and distinguishes it from other set_* sibling tools like set_balance or set_bass.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as set_bass or set_balance. It does not mention prerequisites, contexts where loudness compensation is applicable, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mute or unmute a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| muted | Yes | Mute state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation), and the description adds no additional behavioral context such as side effects or prerequisites. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean toggle action with well-documented parameters, the description is sufficiently complete, though it could note the effect on player audio state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (playerId and muted), so the tool description does not need to add parameter details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mute or unmute a player' clearly states the verb (mute/unmute) and resource (player), distinguishing it from sibling tools like set_volume or set_power.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool or when to consider alternatives, leaving the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a player on, off, or toggle power
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| state | Yes | Power state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so mutation is expected. The description adds no extra behavioral context beyond stating the power actions; it does not disclose side effects, error conditions, or behavior when already in that state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence of 9 words, highly concise and to the point. Every word is necessary and it avoids any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is adequate but lacks details on expected return, error states, or behavior when the player is unreachable. Could be more complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for playerId and state enum. The tool description merely repeats the enum values, adding no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Turn', the resource 'player', and the three specific actions 'on, off, or toggle'. It distinguishes from sibling tools like play_pause or set_mute which handle different functionalities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for power control but provides no explicit guidance on when to use it versus alternatives like play_pause or other player controls. No when-not-to-use or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start or stop a random play mix
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Random mix mode | |
| enabled | Yes | Enable or disable the mix |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, consistent with a mutation operation. The description adds the behavioral trait of toggling (start/stop), but does not disclose details like what happens when already enabled, impact on current playback, or whether it overrides other play modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant phrases. It is concise but could be expanded slightly for clarity without losing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two required parameters and no output schema, the description misses important context: it does not explain the meaning of the 'mode' enum, the effect of 'enabled', or what happens to current playback. It also does not differentiate from many similar play-control siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with brief descriptions for both parameters. The description does not add any semantic information beyond what the schema already provides, such as explaining how 'mode' affects the mix or the effect of 'enabled'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'start' or 'stop' and identifies the resource as 'random play mix', clearly indicating the tool's function. It is distinguishable from sibling tools like 'play_track' or 'play_favorite' by focusing on random mixing, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'play_track' or 'play_favorite'. No context about prerequisites or preferred scenarios is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set repeat mode on a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| mode | Yes | Repeat mode |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds no additional behavioral context, such as whether the repeat mode is toggled or set absolutely, or what happens if the player is not active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. However, it is so minimal that it sacrifices useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description is minimally adequate. It explains setting repeat mode but does not elaborate on the effects of each mode or prerequisites (e.g., player must exist).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the input schema (100% coverage), so the description does not need to add more. The enum values 'off', 'song', 'all' are self-explanatory, but the description could clarify their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets repeat mode on a player, which is a specific verb-resource combination. However, it does not differentiate from sibling tools like set_shuffle or set_random_play, which also control playback modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to choose set_repeat over other playback control tools like set_shuffle or set_random_play.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set shuffle mode on a player
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| mode | Yes | Shuffle mode |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so it's a write operation. The description adds no further behavioral traits—no mention of whether it toggles or sets, no error handling, no confirmation of success. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence that is front-loaded with the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (set shuffle mode), the description is adequate but could mention expected output or side effects. No output schema, so description could hint at what happens after setting (e.g., returns current player state). Moderate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with clear descriptions. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Set' and resource 'shuffle mode' on a player, distinguishing it from sibling tools like set_repeat or set_volume. However, it does not elaborate on the specific modes (off, song, album) which adds some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., player must be active) or when shuffle is appropriate vs. other modes. Sibling tools are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a sleep timer on a player in seconds
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| seconds | Yes | Sleep timer in seconds (0 to cancel) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (modifies state), but the description adds no behavioral context beyond that. It does not explain that setting a timer will stop playback after the specified seconds or that this is a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's action. Every word is necessary; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage and no output schema, the description is adequate but minimal. It tells what the tool does but omits context like how the sleep timer interacts with playback or that 0 cancels the timer, which is only in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats 'in seconds' which is already in the schema, adding no new parameter semantics. It does not elaborate on the meaning or acceptable values beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set', the resource 'sleep timer on a player', and the unit 'in seconds', making the purpose unambiguous. It distinguishes from sibling tools like set_volume or set_power.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to cancel a timer (0 seconds) or prerequisites. The schema includes '0 to cancel' but the description lacks explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set treble level on a player (-100 to 100)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| level | Yes | Treble level (-100 to 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint false). The description adds no additional behavioral context beyond the implied modification, such as side effects, error handling, or dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no waste, but lacks structure (e.g., sections). For a simple tool, this is acceptable and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters, no output schema, and sibling tools that indicate a family of setters, the description covers the essential purpose but omits potential details like invalid playerId handling or level interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters documented. The description mentions the level range, which is already present in the schema, so it adds no new semantics beyond a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'treble level on a player', with a range specification that distinguishes it from sibling tools like set_bass or set_balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or context for usage. The description only states what it does, not when.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the volume of a player (0-100)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to control | |
| volume | Yes | Volume level (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, indicating a write operation. Description does not add new behavioral context beyond the schema and annotations, lacking details on side effects or authorization.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 11 words, efficiently communicating purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with no output schema, the description adequately covers input constraints. However, it could mention return values or state after setting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Set the volume of a player (0-100)', specifying the verb, resource, and input range. It distinguishes itself from sibling tools like set_mute and set_balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like set_mute or set_loudness. The description implies usage but does not specify exclusions or compared scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synchronize two players (master controls slave)
| Name | Required | Description | Default |
|---|---|---|---|
| masterPlayerId | Yes | Player ID that will be the master (controls the slave) | |
| slavePlayerId | Yes | Player ID that will be the slave (controlled by master) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral trait of master-slave control beyond the annotation (readOnlyHint=false). However, it does not disclose side effects, required permissions, or what synchronization entails (e.g., playback mirroring).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action, and contains no redundant information. Every word is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the basic function. It does not explain postconditions or error scenarios, but it is adequate for a straightforward action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description reinforces the roles ('master controls slave') but adds limited new meaning beyond the schema. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('synchronize two players') and specifies the master-slave relationship, distinguishing it from siblings like 'unsync_player' and 'get_sync_status'. The purpose is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when wanting one player to control another, but does not explicitly state when to use this tool vs alternatives like 'unsync_player' or 'get_sync_groups'. No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test connection to the LMS server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond the readOnlyHint annotation. It confirms a read operation but does not disclose potential timeouts, error behavior, or what constitutes a successful test. Annotations already cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and concise, perfectly suitable for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple connection test with no parameters and an annotation indicating read-only, the description provides adequate information. It could be improved by hinting at the expected return value (e.g., success/failure), but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is trivially 100%. Per guidelines, 0 parameters yields a baseline of 4. The description does not need to elaborate on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Test connection' and the resource 'LMS server', making the tool's purpose immediately obvious. It distinguishes well from sibling tools which focus on player control, playlist management, and search operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: to verify connectivity to the LMS server. However, it does not explicitly state when not to use it or mention alternatives, but given the sibling tools, there is no other connection test tool, so exclusion is not necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a player from synchronization (unsync)
| Name | Required | Description | Default |
|---|---|---|---|
| playerId | Yes | Player ID to unsynchronize |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the write operation is expected. However, the description adds no further behavioral details such as side effects, permissions required, or what happens to sync groups. It fails to provide context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action with one parameter, the description is minimally adequate. However, it does not mention return values, error states, or confirmation of success, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'playerId' with a clear description. The tool description adds no additional information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Remove a player from synchronization') and the parenthetical 'unsync' reinforces the purpose. It clearly distinguishes from the sibling 'sync_players' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like sync_players or when not to use it. The description implies usage for unsynchronizing a player but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0add_favoriteadd_to_playlistadd_url_to_playlistbrowse_appclear_playlistdelete_playlist_itemdelete_saved_playlistget_appsget_current_playlistget_decadesget_favoritesget_genresget_new_musicget_player_statusget_playersget_playlistsget_radiosget_random_albumsget_server_statusget_sync_groupsget_sync_statusget_yearsjump_to_playlist_indexmove_playlist_itemplay_app_itemplay_favoriteplay_pauseplay_radio_itemplay_trackplay_urlplaylist_actionrename_saved_playlistrescan_librarysave_playlistsearch_albumssearch_appsearch_artistssearch_radiosearch_trackssearch_tracks_by_genreseekset_balanceset_bassset_loudnessset_muteset_powerset_random_playset_repeatset_shuffleset_sleep_timerset_trebleset_volumesync_playerstest_connectionunsync_playerSome overlapping actions exist, e.g., `play_pause` and `playlist_action` both control playback, and multiple `play_*` tools target different sources but with similar verbs. Tools like `get_current_playlist` and `get_playlists` are distinct but the naming could cause confusion. Overall, most tools have clear targets, but a few ambiguity points lower the score.
Most tools follow a consistent `verb_noun` pattern (e.g., `add_favorite`, `clear_playlist`, `search_tracks`). However, there are minor deviations like `playlist_action` (noun_noun) and `play_pause` (verb_verb), and `jump_to_playlist_index` uses a preposition. These are infrequent, so the overall consistency is good.
With 55 tools, the server is very large. While LMS is a complex domain, many tools are highly specialized (e.g., individual set commands for balance, bass, treble) and could be combined. The high count makes it harder for agents to navigate and select the right tool, exceeding the typical well-scoped range.
The tool set covers virtually all aspects of LMS: playback, playlist management, search, player settings, synchronization, library browsing, app integration, and favorites. There are no obvious dead ends or missing operations for a music server of this level.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for Producer/Riffusion AI music generation
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shermozle/lms-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
