The mcp-kodi server lets an AI assistant control Kodi media players via an MCP interface, enabling comprehensive media management and playback across one or more Kodi instances.
Playback Transport
Play, pause, stop, skip to next/previous items
Play any specific file by path (in-library or not)
Volume & Audio
Adjust volume by relative step, mute/unmute, read current volume/mute state
Now Playing & Notifications
Query current playback state and media info (nowplaying)
Display toast notifications on the Kodi screen (title, message, icon, duration)
Media Search & Discovery
Search music, TV shows, and movies by name, actor, director, season, episode, etc. with paging
List/search contributors (artists, bands, actors, directors) and see where they appear
Inspect audio tracks and subtitles of movies/episodes before playback
Queue Management
Append or insert items into the playback queue
Read current or named playlists without modifying them
Clear all active queues (audio, video, picture) while keeping current item playing
Audio/Subtitle Switching
Switch the active audio track and/or subtitle stream during video playback
Playback History
Query a local playback log with filters (time window, media type, artist, free text, specific IDs); works even when Kodi is offline
Instance Configuration Management
Read, add, update, or remove Kodi instance configurations; passwords are never exposed
Raw JSON-RPC Passthrough (Escape Hatch)
Send any raw JSON-RPC method directly to Kodi; disabled by default and must be manually enabled per instance via allow_rpc: true in the config — the AI cannot enable this itself
Controls a Kodi media player via its JSON-RPC API, enabling transport control (play, pause, stop), volume adjustment, search/discovery of media, queue management, playback history, and an escape hatch for arbitrary Kodi JSON-RPC methods.
An MCP server that lets an AI assistant control a Kodi media player over Kodi's JSON-RPC API. Written in C on the GLib stack.
There is no user-facing CLI: you talk to the AI, the AI calls this server's tools, and the server speaks JSON-RPC to Kodi. The only interface is MCP over stdio.
Where this is going. The plan is a complete, full-featured package that lets any MCP-compatible AI transform the entire media-player experience — not just press buttons, but reinvent how you discover, queue, and enjoy your media. Tell the assistant what you're in the mood for and let it run the room: build the evening's lineup, pick up where you left off last night, adapt on the fly, and surface things you'd never have found yourself. We're aiming for something genuinely new — a mind-blowingly different way to live with your media player.
Status — early, but already remarkable (v0.2.0dev). A growing set of dedicated, purpose-built tools covers transport, volume, search, queue management, and playback history. What makes the build capable beyond that list is the
rpcescape hatch (see below): an opt-in passthrough to any Kodi JSON-RPC method. Between the first-class tools and that escape hatch, an assistant can already drive nearly everything Kodi exposes — remarkable enough that we decided to publish early rather than wait for the full vision to land. Expect frequent releases.
Each tool targets a configured Kodi box by key (instance); omit it and the
configured default box is used (with one exception: history spans all
boxes when instance is omitted).
Transport & audio
Tool | What it does |
| Press Play on the remote — resume or begin playback on the target box. |
| Press Pause — pause the active player. |
| Press Stop — stop the active player and clear the playlist it was consuming, so no queued items linger. |
| Press Skip Next — advance to the next track/chapter in the active playlist. |
| Press Skip Previous — go to the previous track/chapter (or restart the current item). |
| Adjust the volume by a relative signed step (percentage points); step |
| Mute the box's audio output. |
| Unmute the box's audio output. |
| Report what is playing without changing anything — also a reachability + state probe. |
| Show a notification toast on the box's screen — title + message, with an optional icon ( |
Search & discovery
Tool | What it does |
| Find playable leaf files by name across |
| Find or list people — bands, solo artists, composers, actors, directors — by optional name substring and/or |
| Inspect a movie or episode's audio tracks and subtitles before playback, from Kodi's cached |
| Switch the audio track and/or subtitle of the video now playing, by the |
Playback & queue
Tool | What it does |
| Play one file by path (typically a |
| Append an item behind the one now playing (a |
| Read a queue without changing it — the active player's playlist, or a named one ( |
| Empty all queues (audio, video, picture) in one call. The current item keeps playing — only the items queued behind it are removed. Not undoable; inspect with |
Bookkeeping & escape hatch
Tool | What it does |
| List recently played items from the local playback log, written as a side effect of every playback-affecting call. Optional ISO-8601 |
| Read or modify the server's own instance config ( |
| Escape hatch — send a raw JSON-RPC method to Kodi and return its reply unchanged. Off by default; opt-in per instance (see below). |
Most action tools return a small player-state snapshot — { "state": "playing"|"paused"|"stopped", "type", "time", "totaltime", "progress", "nowplaying": { "media", "id", "file", "label", "title", … } } — keeping the
player status (state/type/time/totaltime plus a legible progress clause
like "15:38 / 46:40 (33%)") at the top and nesting the loaded media under
nowplaying, with its per-media fields where they apply (artist, album,
track, showtitle, season, episode) — so the assistant always sees the
effect of its action: this covers
play/pause/stop, playfile, queue, dropplaylists, and nowplaying. The
audio tools volume/mute/unmute return { "muted", "volume" } (volume
also adds the min/max bounds). The read tools (searchmedia,
contributors, getplaylist, history) return their own paged result
envelopes.
Every tool except rpc declares these shapes as an MCP outputSchema
(spec revision 2025-06-18) and mirrors each successful result as
structuredContent alongside the JSON text block, so schema-aware clients
can validate and consume results without parsing. Each description also
states the result shape inline — the channel every client shows the model.
rpc declares none: it returns Kodi's raw reply verbatim, which has no
fixed shape.
rpc escape hatchrpc POSTs any JSON-RPC method you name to the target box and hands back Kodi's
raw result, unshaped:
// e.g. raise the GUI volume, activate a window, send an input action…
rpc { "instance": "hall", "method": "GUI.ActivateWindow", "params": { "window": "home" } }This is powerful and unconstrained, so it is disabled by default and gated
per instance. A box permits rpc only when its config object carries
"allow_rpc": true. That flag is granted only by hand-editing config.json —
it is intentionally not one of the fields the instances tool can write, so
the assistant can never enable its own escape hatch. Opting a box in is an
explicit, out-of-band human decision; calling rpc on a box that hasn't opted in
returns a clean error and makes no Kodi request.
See the full Kodi method surface in docs/kodi-jsonrpc-catalog.md.
Related MCP server: mcp-mpv-player
Before mcp-kodi can reach a box, that Kodi has to allow remote control. In Kodi,
open Settings → Services → Control and turn on Allow remote control via
HTTP, then set a username and password right there. Those same credentials
go into this server's config as auth, in user:pass form.
mcp-kodi speaks HTTPS, so for normal use you put a small reverse proxy in
front of Kodi's plain-HTTP control port. Caddy with
tls internal is the easy choice: it terminates HTTPS and forwards to Kodi on
localhost. Point the instance's host at the proxy and set insecure: true
to accept its self-signed certificate. The full step-by-step walkthrough — the
exact Kodi menus, installing Caddy, and the Caddyfile — is in
docs/kodi-server-setup.md.
Most Kodi players already sit on a home LAN behind a router/firewall and are not exposed to the internet, so turning on the HTTP control interface there is generally safe. The login/password and the HTTPS proxy add defence in depth — just keep the proxy on a trusted network and don't forward its port to the open internet.
There are two ways to add a box. The simplest is to let the AI do it: once
the MCP server is loaded, just tell the assistant about your Kodi — its address
and login — and it registers the instance for you through the instances tool
(set), writing the entry into the config file.
You can also do it by hand, by editing config.json directly. Two things
are deliberately off-limits to the AI, so hand-editing is the only way to set
them:
The password. auth is write-only — the instances tool never returns a
stored password, so the assistant can register a box but can never read back
the credentials. If you'd rather the AI never see the password at all, type it
into the file yourself.
The escape hatch. allow_rpc is not a field the instances tool can
write, so the assistant can never grant itself the unrestricted rpc
passthrough. Enabling it is always an explicit, out-of-band human edit.
The server reads ${XDG_CONFIG_HOME:-~/.config}/mcp-kodi/config.json. It holds a
map of named Kodi instances and names one default:
{
"version": 2,
"default": "hall",
"instances": {
"hall": { "name": "Living Room TV", "host": "hall.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true, "allow_rpc": true },
"bedroom": { "name": "Bedroom", "host": "bedroom.example.local:8443", "auth": "kodi:<password>", "scheme": "https", "insecure": true }
}
}Field | Meaning |
instance key | The short id every tool references ( |
| The key used when a tool omits |
| Optional human-readable label, surfaced in the tool schema. |
|
|
| HTTP Basic credentials as |
|
|
|
|
|
|
The file is created 0600 in a 0700 directory (it holds passwords) and is
written back atomically when the instances tool changes it.
No config file? A single box can be defined entirely from the environment,
applied to an implicit default instance: KODI_HOST, KODI_AUTH,
KODI_SCHEME, and -k in KODI_CURL_OPTS (→ insecure). With neither a file
nor env, the server exits with a clear error telling you to configure.
A legacy version: 1 flat file (single top-level host/auth/…) is read as one
instance named default and rewritten in the version: 2 shape on the next save.
Note: config is read once at startup. After hand-editing
config.json(e.g. to setallow_rpc), restart the server so it re-reads the file.
# user scope makes the tools available in every project
claude mcp add --scope user kodi -- /path/to/mcp-kodi/src/mcp-kodiAdd a stdio server entry pointing at the binary:
{
"mcpServers": {
"kodi": {
"command": "/path/to/mcp-kodi/src/mcp-kodi"
}
}
}Once registered, ask your assistant things like "what's the player doing in the
living room?" (nowplaying), "find Pink Floyd's Animals and play it" (searchmedia →
playfile), or "mute the bedroom" (mute).
config.json stores Kodi passwords in plaintext, mode 0600. Protect it like
any other credential file.
insecure: true disables TLS certificate verification for that box. It is the
right choice behind Caddy's tls internal self-signed cert, but means the
connection is encrypted, not authenticated against a CA — keep the proxy on a
trusted network.
The rpc escape hatch can invoke any JSON-RPC method (including
destructive ones like System.Shutdown). It stays off until you deliberately
set allow_rpc: true for a specific box. Enable it only where you trust the
assistant to operate unconstrained.
Copyright © 2026 Laszlo Pere <laszlopere@gmail.com>. An independent, clean-room implementation.
Free software, licensed under the GNU General Public License v3.0. You may redistribute and/or modify it under those terms; it comes with no warranty. See LICENSE for the full text.
If this project is useful to you, please consider supporting it through GitHub Sponsors. Every bit of support keeps it alive — funding the time to ship the frequent releases this is built on, and to chase the full vision.
And if you're still on the fence: ask your Claude whether this project is good for you — and if it recommends it (as most Claude do), support it by becoming a sponsor.
Find or list contributors (bands, solo artists, composers, actors, directors): optional name substring, optional type (band/composer/actor/director) — e.g. {type: "band"} lists all bands. Rows {name, in: [albums|songs|movies|tvshows]} say where each name yields hits — feed the exact name back into searchmedia to drill. Returns { "total", "returned", "offset", "truncated", "rows" }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| name | No | Person name to look for (substring, case-insensitive): a band, solo artist, composer, actor, or director. Omit to list everyone (of `type` when given). | |
| type | No | Contributor kind to list. band = album-level music artist (closest Kodi gets to a band — includes headline solo artists); composer/actor/director are literal. Omit for all kinds. "List all bands" = {type: "band"} with no name. | |
| limit | No | Max rows to return (default 50, max 500). Page with offset. | |
| offset | No | Number of rows to skip — paginate together with limit. | |
| count | No | When true, return only the total match count (zero rows). |
| Name | Required | Description |
|---|---|---|
| total | Yes | Full match count, before any paging. |
| returned | Yes | Rows in this page. |
| offset | Yes | Rows skipped before this page. |
| truncated | Yes | Whether matches remain beyond this page. |
| rows | Yes | The matching people, merged and sorted by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: the tool is read-only, returns a structured object with total/returned/offset/truncated/rows, and explains that rows contain a 'name' and an 'in' array indicating where the name appears. The truncation signal and pagination implications are clear.
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?
Two sentences with zero waste. The first sentence bundles purpose, parameters, and an example. The second sentence covers output structure and integration with sibling tool. Every part 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?
Given the tool has 6 parameters (none required), an enum, and an output schema, the description covers all key aspects: usage patterns, output format, pagination hints, and integration with searchmedia. No gaps remain for an agent to misinterpret.
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 baseline is 3. The description adds value by explaining how parameters interact (e.g., 'Omit to list everyone (of type when given)', using count to return only total, and the pagination pattern). It gives a concrete example ('List all bands = {type: "band"} with no name') that clarifies the enum.
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 opens with a specific verb-object pair ('Find or list contributors') and immediately clarifies the resource (bands, solo artists, composers, actors, directors). It distinguishes itself from sibling searchmedia by explaining that the output name is meant to be fed back into searchmedia for drilling. This makes the tool's role clear and complementary.
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 explains when to use the tool (to list contributors by type or search by name) and provides a concrete downstream action ('feed the exact name back into searchmedia'). It does not explicitly state when not to use it or list alternatives, but the context is sufficient for correct invocation among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Empty all queues: clear the audio, video and picture playlists in one call. The current item keeps playing — only the queued items behind it are removed — so playback is never interrupted. Not undoable; inspect with getplaylist first if the content matters. Returns the player-state snapshot — whatever was playing still is, with nothing queued behind it.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses that the action is not undoable, that playback is never interrupted, that it clears all three playlists, and that it returns a player-state snapshot. No behavior is hidden or misrepresented.
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 three sentences, front-loading the main action ('Empty all queues') and providing necessary caveats and return value. Every sentence adds value with no redundancy or 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 tool that clears queues, the description covers the action, the behavior (non-interrupting, not undoable), the return value (player-state snapshot), and provides a safety hint (inspect first). With an output schema present (mentioned), the description is complete enough for an agent to invoke correctly.
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% (the only parameter 'instance' is documented in the schema). The description does not add any additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate given 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 empties all queues (audio, video, picture) and distinguishes itself from siblings like 'getplaylist' (inspect) and 'queue' (add) by specifying it clears queued items while keeping the current item playing.
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?
Explicit guidance is given: 'Not undoable; inspect with getplaylist first if the content matters.' This tells the agent when not to use it (if content matters) and provides an alternative (getplaylist). It also implies when to use: when you want to clear queues without interruption.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the queue without changing it: the items of the active player's playlist — or of a named one (audio/video/picture), which always wins — plus the position of the now-playing item. An empty queue is an empty list. Returns { "type"?, "total", "position"?, "items": [ { "id", "file", "label", "type" } ] }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| type | No | Which playlist to read. Always wins when provided — reads that playlist even while another plays, the only way to inspect an inactive queue. Omitted reads the active player's playlist. |
| Name | Required | Description |
|---|---|---|
| type | No | The playlist read, when one was resolved. |
| total | Yes | Number of queued items. |
| position | No | Index of the now-playing item — present only when the playlist read is the active player's own. |
| items | Yes | The queued items, in playback order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states the tool is non-destructive ('Read the queue without changing it'), describes the return format, and covers edge cases like an empty queue returning an empty list. It also reveals the override behavior of the 'type' parameter. This is good behavioral 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 extremely concise: two sentences that front-load the purpose and then provide additional context. Every sentence serves a purpose without unnecessary elaboration.
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 low complexity (2 optional parameters, output schema present), the description is fairly complete. It covers the return structure, empty queue behavior, and the parameter override. It could mention error scenarios (like invalid instance or no player active), but for a read-only tool 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%, so baseline is 3. The description adds value beyond the schema by explaining that specifying a type is 'the only way to inspect an inactive queue' and that the named playlist 'always wins'. This supplements the schema description for the 'type' parameter. The 'instance' parameter is not elaborated, but the schema already covers it 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 it reads the queue without modifying it, and specifies the resource as the active player's playlist or a named one (audio/video/picture). The verb 'Read' and resource are explicit, and it distinguishes from sibling tools like 'nowplaying' (which likely shows only the current item) by indicating it returns the full playlist and position.
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 clear context for when to use the tool (reading the queue) and notes that a named playlist 'always wins', allowing inspection of inactive queues. It implicitly suggests not to use this for changing state, and sibling tools like 'play', 'pause', 'stop' are for control. However, it does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recently played items from the local playback log. Filter with an ISO-8601 window (since/until), media/kind/artist, a free-text match or an exact id; page with limit/offset/order, or ask for a count only. An omitted instance returns all boxes. Reads only the local log — no Kodi call, so it works even when no box is reachable. Returns { "total", "returned", "offset", "truncated", "entries": [ { "at", "instance", "kind", "media", "title", "artist", … } ] }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Restrict to one Kodi instance by key. Omitted returns entries from ALL instances — note this differs from other tools, where an omitted instance means the default box. | |
| since | No | Only entries at or after this ISO-8601 time (e.g. "2026-06-01T00:00:00Z"). Omitted = from the beginning of the log. Compute relative windows ("last 7 days") yourself. | |
| until | No | Only entries at or before this ISO-8601 time. Omitted = up to now. | |
| limit | No | Max entries to return (default 50, max 1000). When more match, the reply sets "truncated": true — page the rest with offset. | |
| offset | No | Number of matching entries to skip before this page — paginate together with limit, keeping the same order. | |
| order | No | Result order: "newest" first (default) or "oldest" first to replay a session in the order it happened. | |
| count | No | When true, return only the total match count (zero entries) — a cheap "how many times / how much did X play". | |
| media | No | Keep only entries of this media kind (song/episode/movie/musicvideo/picture/channel) — e.g. "movies only". | |
| kind | No | Keep only entries of this broad kind: audio or video — e.g. "what music did I play". | |
| artist | No | Keep only entries whose performer contains this (substring, case-insensitive) — the music-by-artist filter ("everything Pink Floyd I played"). Only as good as the captured artist tag. | |
| match | No | Free-text substring (case-insensitive) over an entry's human fields — title, album, show, label and artist — to narrow the log without knowing ids. | |
| id | No | Exact library id to match ("every time THIS item played"). Ids are per media type, so pair with media; feed back a searchmedia or getplaylist row's id. |
| Name | Required | Description |
|---|---|---|
| instance | No | The instance filter, echoed when one was given. |
| since | No | The window's lower bound, echoed when one was given. |
| until | No | The window's upper bound, echoed when one was given. |
| total | Yes | Full match count, before any paging. |
| returned | Yes | Rows in this page. |
| offset | Yes | Rows skipped before this page. |
| truncated | Yes | Whether matches remain beyond this page. |
| entries | Yes | The matching history records. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it reads only local log, requires no Kodi call, works even when no box reachable, and explains the behavior of omitted instance (returns all boxes). Since no annotations are provided, the description fully covers behavioral traits.
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 dense but well-structured within a single paragraph. It front-loads the main purpose, then systematically covers filters, pagination, behavioral notes, and return format. Every sentence adds value without repetition.
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 high complexity (12 parameters, rich filtering, pagination, output schema), the description is complete. It covers all usage aspects, behavioral notes, and the return structure, leaving no ambiguity for an agent to select and invoke the tool correctly.
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?
Adds significant meaning beyond a fully covered schema (100% coverage). For instance, explains that omitted instance differs from other tools, advises computing relative windows for since/until, describes default/max for limit and truncated flag, explains offset pagination, order use case, count as cheap total, media/kind examples, artist substring limitation, match field scope, and id pairing with media.
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 lists recently played items from the local playback log, with specific verb and resource. It distinguishes from sibling tools like nowplaying, getplaylist, and searchmedia by focusing on historical playback log.
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?
Provides explicit guidance on when to use, including filtering options (ISO-8601 window, media/kind/artist, free-text, exact id), pagination (limit/offset/order), and a note that omitted instance returns all boxes, differing from other tools. Also implies alternatives for library search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or modify the configured Kodi instances (action: get/set/remove). Manages the MCP server's own config, not a Kodi device. Returns { "default", "instances": [ { "key", "host", "scheme", "insecure", "has_auth", "allow_rpc", … } ] }.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation: "get" lists configured instances, "set" creates/updates one, "remove" deletes one. | |
| key | No | Instance key — the short id tools target. Required for "set" and "remove". | |
| name | No | Human-readable display label ("set"). | |
| host | No | Kodi host as "host[:port]" ("set"). | |
| auth | No | HTTP Basic credentials as "user:pass" ("set"). Write-only: never returned by "get". | |
| scheme | No | URL scheme, "http" or "https" ("set"; default "https"). | |
| insecure | No | Accept a self-signed TLS certificate, like curl -k ("set"). | |
| default | No | When true on "set", make this instance the default. |
| Name | Required | Description |
|---|---|---|
| default | Yes | Key of the default instance, or null when none is configured. |
| instances | Yes | The configured instances, in sorted key order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the tool's scope (server config), actions, and return structure. It also notes that auth is write-only, adding important behavioral detail beyond the schema.
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: one sentence plus a compact return format listing. It front-loads the purpose and includes no filler. Every sentence 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?
Given the tool's complexity (8 parameters, 1 required, no nested objects), the description covers the overall purpose, scope, and return structure. It is complete enough for an AI agent to understand usage without additional 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 description coverage is 100%, providing baseline 3. The description adds value by summarizing actions, showing the output format, and noting the write-only nature of auth, which goes 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 tool reads or modifies configured Kodi instances, with explicit actions (get/set/remove). It distinguishes from sibling tools by clarifying it manages the MCP server's own config, not a Kodi device.
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 specifies that the tool manages the MCP server's own config, implying it is not for direct Kodi control. While it doesn't list explicit alternatives, the scope is clear, and sibling tools cover other functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mute the target instance's audio output. Returns { "muted", "volume" }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| muted | Yes | Whether audio output is muted. |
| volume | Yes | The application volume, 0-100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the return structure (muted, volume) but lacks details on side effects, idempotency, or prerequisites beyond the parameter.
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 two sentences with no fluff, front-loading the action and return value, making it efficient and immediately informative.
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 and an output schema, the description covers the core functionality and return. It could mention idempotency or behavior when already muted, but is adequate for most use cases.
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 the description adds no information beyond the schema's parameter description, which already explains the 'instance' parameter and default behavior.
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 specifies a concrete verb ('Mute') and resource ('target instance's audio output'), clearly distinguishing it from sibling tools like 'unmute' and 'volume'.
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 (to silence audio output) but does not explicitly state when to use it versus alternatives like 'unmute' or 'volume', nor does it provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report what is playing on the target instance without changing anything — also a reachability and state probe. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }; { "state": "stopped" } when idle.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden and effectively discloses the read-only nature, return format, and idle state handling.
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?
Two sentences efficiently convey purpose, behavior, and return format 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?
For a simple tool with one optional parameter and an output schema, the description covers purpose, behavior, and return values adequately.
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 the description does not add extra meaning beyond the schema's own parameter description.
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 reports what is playing on the target instance and explicitly notes it does not change anything, distinguishing it from siblings like play, pause, or stop.
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 it is safe and used as a reachability probe, but does not explicitly state when to use it versus alternatives like getplaylist or history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press Pause on the Kodi remote: pause the active player on the target instance. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the core action (pause) and return value (player-state snapshot). With no annotations, it carries the full burden but lacks details on idempotency or state when already paused.
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?
Two sentences: first states purpose and action, second lists returned fields. No redundant information.
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?
Tool is simple (one optional param, output schema exists). Description covers action and return value adequately for an AI agent to invoke correctly.
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 'instance'. Description adds no further meaning beyond the schema, meriting 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?
Clearly states it pauses the active player on the target Kodi instance, distinguishing it from sibling tools like 'play', 'stop', 'mute'. The verb 'pause' uniquely identifies the action.
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 pause vs alternatives like 'stop' or 'mute'. Does not mention conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press Play on the Kodi remote: resumes paused playback only — it cannot start new content (with nothing loaded it is a no-op); use playfile to start something. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it is a no-op when nothing is loaded, and returns a specific state snapshot. It also details the return fields.
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?
Two sentences that are front-loaded with the main action and constraints, with zero 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 low complexity (one optional parameter, no required, output schema partially described), the description provides complete context: purpose, constraints, return format, and differentiation from 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% (one parameter with description). The description adds no 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?
The description clearly states the verb 'Press Play' and the resource 'Kodi remote', and distinguishes from the sibling 'playfile' by noting it only resumes paused playback and cannot start new content.
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?
Explicit when to use ('resumes paused playback only'), when not to use ('cannot start new content'), and provides an alternative ('use playfile to start something').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play one file by path (e.g. a searchmedia result's file): Player.Open auto-selects the audio/video player. Works for any reachable path, in-library or not. A file missing from disk (stale library entry) is reported as an error. Returns the player-state snapshot { "state", "media", "id", "title", "artist", "time", "totaltime", … }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| file | Yes | Path of the file to play — the `file` field of a `searchmedia` result row. Any path Kodi can reach works, in-library or not. |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses key behaviors: uses Player.Open, auto-selects player, error reporting for missing files, and return structure. Lacks details on auth or side effects but sufficient for playback intent.
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?
Concise three sentences with front-loaded core action. Every sentence adds information, no 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?
Covers core functionality, error handling, and return value. Output schema exists for return details, making the description complete for this simple 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 coverage is 100%, and description adds context beyond schema (e.g., file comes from searchmedia, instance default behavior). Adds value without redundancy.
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 'Play one file by path', specifying the verb and resource. Distinguishes itself from siblings like 'play' and 'queue' by focusing on direct file playback via path.
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?
Provides usage context such as 'a searchmedia result's file' and 'works for any reachable path', but does not explicitly compare to siblings or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue an item behind the one now playing, for continuous playback: a searchmedia row's library id (type+id) or a file path; next:true plays it right after the current item. Something must already be playing (start with play/playfile). An item whose file is missing from disk (stale library entry) is refused. Returns the player-state snapshot, unchanged by the add — the current item keeps playing.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| type | No | Kind of library id passed in `id` — picks the item key (songid/episodeid/movieid). Required with `id`; not used with `file`. Must match the playing queue: a song joins audio playback, an episode or movie joins video playback. | |
| id | No | Library id of the item to queue — the `songid`/`episodeid`/`movieid` of a `searchmedia` result row, matching `type`. Give exactly one of `id` or `file`. | |
| file | No | Path of the file to queue — the `file` field of a `searchmedia` result row; any path Kodi can reach works. Give exactly one of `id` or `file`. | |
| next | No | When true, insert the item right after the one now playing ("play next") instead of appending to the end of the queue. |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly states that items whose files are missing from disk are refused, that the current item keeps playing (unchanged), and that the return value is a player-state snapshot. This covers safety, side effects, and return behavior comprehensively.
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 concise with two sentences, front-loading the primary purpose and key constraints. Every sentence adds critical information without redundancy or 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 presence of an output schema, the description appropriately avoids detailing return values. It covers prerequisites, input modes (library id vs. file), conditions for 'type', and the nuance of 'next'. The parameter descriptions in the schema are thorough, and the description fills remaining gaps, making it fully complete for a queuing 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%, so the schema already documents all parameters. The description adds value by explaining the relationship between 'type' and 'id' (matching rows from 'searchmedia'), the mutually exclusive 'id'/'file' constraint, and the semantics of 'next'. This enriches understanding 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 'queue' combined with resource context ('item behind the one now playing for continuous playback') and explicitly distinguishes between library id and file path inputs. It clearly differentiates from sibling tools like 'play' and 'playfile' by stating the prerequisite that something must already be playing.
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 clear context for when to use the tool: 'Something must already be playing (start with play/playfile).' It also explains the 'next' parameter behavior. However, it does not explicitly state when not to use it or name alternative tools beyond the prerequisite, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: send a raw JSON-RPC method to Kodi and return its reply unchanged. Disabled unless the target instance has opted in (allow_rpc in the server config, set by hand only).
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| method | Yes | JSON-RPC method to invoke verbatim, e.g. "GUI.ActivateWindow" or "Input.Up". Returns Kodi's raw result unchanged. Escape hatch for methods the dedicated tools don't model — disabled unless the target instance has opted in ("allow_rpc" in the server config, set by hand only). No configured instance currently permits it. | |
| params | No | Parameters object passed straight through to the method. Omit for a method that takes none. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it passes through raw replies unchanged and is disabled unless configured, providing behavioral context beyond the schema.
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?
Two sentences with key information front-loaded, though the second sentence is somewhat lengthy. Efficient overall.
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?
Explains usage, constraints, and behavior. Lacks information about error handling or return format details, but sufficient for this specialized 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 coverage is 100% but the description adds clarity: 'method' is verbatim, 'params' passed straight through, 'instance' defaults. Adds value beyond 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 identifies the tool as an 'escape hatch' for sending raw JSON-RPC methods to Kodi, distinguishing it from dedicated tools that model specific methods.
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?
It states when to use (for methods not modeled by dedicated tools) and conditions (requires opt-in, disabled by default), but lacks explicit comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find playable files by name: music/tv-show/movie, drilled to leaf files with paging (limit/offset) and a total count. For music, title means the ALBUM name — songs cannot be matched by their own title. Movie and tv-show queries can also filter by actor/director. Finds media items only — for people lookups (bands, artists, who is in the library) use contributors. Returns { "type", "total", "returned", "offset", "truncated", "rows": [ { "file", "id", "label", "title", … } ] }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| type | Yes | Media kind to search: music | tv-show | movie. | |
| artist | No | Music only: performer name (substring, case-insensitive). Resolves the artist; music needs artist or title. | |
| actor | No | movie/tv-show only: cast-member name (substring, case-insensitive). For tv-show it matches episode cast, which includes guest stars; combinable with title. | |
| director | No | movie/tv-show only: director name (substring, case-insensitive). For tv-show it matches per-episode directors; combinable with title. | |
| title | No | Container/title to match (substring, case-insensitive): album for music, show for tv-show, the movie title for movie. tv-show needs title, actor or director; without title the person is matched library-wide and rows carry showtitle. Music without artist resolves the album library-wide. | |
| season | No | tv-show only: season number to narrow the episodes. | |
| number | No | Position within the container: track number (music) or episode number (tv-show). | |
| limit | No | Max leaf rows to return (default 50, max 500). Page with offset. | |
| offset | No | Number of leaf rows to skip — paginate together with limit. | |
| count | No | When true, return only the total match count (zero rows) — a cheap count. |
| Name | Required | Description |
|---|---|---|
| type | Yes | The searched media type, echoed back. |
| total | Yes | Full match count, before any paging. |
| returned | Yes | Rows in this page. |
| offset | Yes | Rows skipped before this page. |
| truncated | Yes | Whether matches remain beyond this page. |
| approximate | No | Present (true) when total/paging are app-side estimates (a substring title matched several albums). |
| resolved | No | The container the query resolved to — { "artist"?|"show"?, "artistid"|"tvshowid" } — when it drilled through one. |
| rows | Yes | The matching leaf rows, paged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description fully discloses behavior: pagination via limit/offset, cheap count via 'count' boolean, drilling to leaf files, return structure (type, total, returned, offset, truncated, rows) with key fields. It also explains edge cases like album-level search for music and cast/director matching per episode.
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?
Description is a single paragraph with efficient front-loading of main purpose, followed by key constraints and return format. Every sentence adds value without redundancy. Appropriate length for the tool's complexity.
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 11 parameters, 100% schema coverage, and an implied output schema (listed in description), the description covers all necessary context: pagination, cheap count, media-type-specific behaviors, and exclusion of people lookups. No gaps remain for an AI agent to successfully invoke the 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 covers all 11 parameters with 100% description coverage, but description adds critical meaning beyond schema: title means album for music; for tv-show, actor matches episode cast including guest stars; director per episode; library-wide matching when certain parameters omitted. This enriches parameter understanding.
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 tool finds playable files by name for music, tv-show, movie with pagination and total count. It explicitly distinguishes itself from the sibling 'contributors' tool for people lookups. The verb 'Find' and resource 'playable files' are specific and unambiguous.
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?
Description provides explicit when-to-use (for media items) and when-not-to-use (for people, use contributors). It details constraints per media type: music title is album name, tv-show requires title/actor/director, and combinability of filters. This guides correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press Stop on the Kodi remote: stop the active player on the target instance and clear the playlist it was playing, so no queued items linger. Returns the player-state snapshot — { "state": "stopped" } after a successful stop.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| state | Yes | Playback state; "stopped" means nothing is loaded. |
| type | No | The active player kind. |
| media | No | Real media type (song/episode/movie/musicvideo/…); "unknown" for an off-library file. |
| id | No | Library id of the playing item; -1 when off-library. |
| file | No | Path of the playing item. |
| label | No | Kodi's display label for the item. |
| title | No | The item's title (may be empty). |
| showtitle | No | TV episode: the show's name. |
| season | No | TV episode: season number. |
| episode | No | TV episode: episode number. |
| album | No | Song: the album name. |
| artist | No | Song: the performers, an array of strings. |
| track | No | Song: track number on the album. |
| time | No | Playback position { hours, minutes, seconds, milliseconds }. |
| totaltime | No | The item's duration, same shape as time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect (clear playlist) and return format, but does not mention behavior when no active player exists or any potential edge cases. With no annotations, description could be more thorough.
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?
Two sentences, front-loaded with main action, concise and to the point. 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?
Complete for a low-complexity tool: describes action, side effect, and return format. Output schema is implied in the description.
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 the single parameter (instance) at 100% coverage. Description does not add additional meaning beyond the schema, 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?
Description clearly states action ('stop the active player') and resource ('target instance'), with explicit side effect ('clear playlist'). Distinguishes from sibling tools like 'pause' by mentioning playlist clearing.
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 use for stopping playback entirely (including clearing queue), contrasting with 'pause'. Lacks explicit when-not guidance but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unmute the target instance's audio output. Returns { "muted", "volume" }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). |
| Name | Required | Description |
|---|---|---|
| muted | Yes | Whether audio output is muted. |
| volume | Yes | The application volume, 0-100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the return format '{ "muted", "volume" }' but does not disclose potential side effects, permissions, or failure 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?
Extremely concise: one sentence and a return note. No wasted words, 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?
Given the tool's simplicity (one optional parameter and an output schema), the description covers the core action and return structure. The existence of an output schema compensates for lack of return details in the description. Slightly lacking in error or prerequisite information.
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 'instance,' which is already described in the input 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?
The description clearly states the verb 'Unmute' and the resource 'target instance's audio output.' It is specific and distinguishes from sibling tools like 'mute' and 'volume' by its opposite action.
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 'mute' or 'volume.' Usage is implied but not directly stated, lacking when-not-to-use or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adjust the target instance's volume by a relative step (in percentage points); step 0 or omitted just reports the current volume. Returns { "muted", "volume", "min", "max" }.
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | Target Kodi instance. Omitted uses the default ("(null)"). | |
| step | No | Relative volume change in percentage points. 0 or omitted reads the current volume without changing it; positive raises, negative lowers. The result is clamped to the 0-100 range reported as min/max. |
| Name | Required | Description |
|---|---|---|
| muted | Yes | Whether audio output is muted. |
| volume | Yes | The application volume, 0-100. |
| min | Yes | Lower volume bound (always 0). |
| max | Yes | Upper volume bound (always 100). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses relative adjustment, clamping, and return format; no annotations provided, so description carries burden effectively, though permissions or side effects not mentioned.
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?
Two concise sentences plus return format note; front-loaded with purpose, 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?
Complete for a low-parameter tool with output schema; covers adjustment, reading, and return values.
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?
Adds meaning beyond 100% schema coverage: clarifies step as percentage, clamping, instance default, and reading behavior.
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 adjusts volume by a relative step and reports current volume when step is 0 or omitted, distinguishing it from siblings like mute/unmute.
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?
Implied usage for adjusting or reading volume, but no explicit guidance on when to use vs alternatives like mute, or exclusions.
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.
v0.1.0contributorsdropplaylistsgetplaylisthistoryinstancesmutenowplayingpauseplayplayfilequeuerpcsearchmediastopunmutevolumeScored across 16 tools
Each tool has a distinct, well-defined purpose (playback, volume, playlist, search, history, config). Potential overlaps like play vs playfile are clearly differentiated by descriptions.
All tool names are lowercase, single words or compound words without underscores or camelCase, forming a consistent and predictable pattern.
16 tools cover the essential operations for a Kodi remote control without being excessive. The scope feels well-balanced.
Covers core playback, volume, playlist, and search operations. Missing advanced features like seeking or subtitle control, but these are not essential for basic remote control.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
