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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the cached-source behavior (no playback), the embedded-only limitation, the failure mode where external .srt sidecars and unscanned files yield empty arrays, and the meaning of "index" as a handle for the setters. These are exactly the non-obvious traits an agent 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?

Front-loaded with purpose and scope, then constraints, then return shape — every sentence earns its place. It is dense and information-packed, with the streamdetails limitation and index mapping packed into the tail, but nothing is wasted.

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 a pre-playback read tool with an output schema, no annotations, and fully documented params, the description covers everything an agent needs: purpose, naming inputs, output shape, and the embedded-only caveat. Even though the output schema exists, restating the return shape harms nothing.

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 baseline is 3. The description still adds value beyond the schema by tying id/file back to their origin (a searchmedia movie/episode row) and restating the mutually-exclusive naming choice, giving semantic grounding rather than duplicating field text.

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?

States a specific verb and resource (inspect audio tracks and subtitles) plus a precise scope: pre-playback, from Kodi's cached streamdetails. This cleanly separates it from the sibling setters (set_audio_and_subtitle) and the playback tools, so an agent can route correctly without opening a schema.

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 establishes the key usage context (inspect BEFORE playback, no playback triggered) and points at the relevant alternatives by referencing the audio/subtitle setters that consume the returned "index" and searchmedia rows that supply the id/file. It stops short of an explicit when-not-to-use or a named sibling, so it is clear context rather than full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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

With no annotations, the description carries the full behavioral burden and does so: it defines exactly what is destroyed (only queued items behind the current one), guarantees playback continues uninterrupted, warns the operation is not undoable, and describes the resulting player state. This is precisely the destructive/reversibility context an agent 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?

Four short sentences, each earning its place: scope, effect on current playback, reversibility warning, return state. The core action is front-loaded and there is no 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?

Although an output schema exists (and a return description is therefore optional), the description still tells the agent what the snapshot will look like. Combined with the destruction scope and irreversibility warning, nothing needed to call this tool safely is missing.

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 'instance' parameter, so the schema fully documents it. The description adds nothing about the instance parameter (or its default), so the baseline 3 applies rather than a higher 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?

Specific verb + resource: 'Empty all queues: clear the audio, video and picture playlists in one call.' It states scope (all three playlists at once) and implicitly distinguishes itself from sibling getplaylist, which it names. An agent can tell this apart from stop/skipnext without opening the schema.

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 gives a clear precondition — 'Not undoable; inspect with getplaylist first if the content matters' — which routes to the alternative sibling and warns about irreversibility. It stops short of an explicit when-not-to-use statement (e.g. how it differs from stop), so it is clear context rather than full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.

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.

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

No annotations are provided, so the description carries the full burden: it discloses that the tool is non-playback-affecting, that the icon and display time are optional, that defaults exist (default icon, 5000ms), and that Kodi clamps small values. That is solid disclosure of side effects and edge behavior for a UI-affecting tool, though it does not state whether the toast is queued, whether it blocks, or permission requirements.

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 the action and scoping, then parameters. Tight and waste-free overall, though the trailing return-shape sentence partially duplicates the existing output schema and is the weakest-earning clause.

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 params at 100% schema coverage, an output schema present, and no nested objects, the description supplies everything an agent needs: purpose, playback-neutral scope, parameter defaults, and clamping behavior. Nothing material is missing.

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 every parameter (image, title, message, instance, displaytime) is already fully documented in the schema, including the info/warning/error keywords and the ms unit. The description largely restates those same facts rather than adding syntax, format, or constraint details beyond the schema, so the baseline 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?

States a specific verb+resource ('Show a notification toast on the Kodi box's screen') and immediately disambiguates from the entire playback-oriented sibling set with 'Doesn't touch playback.' An agent can identify this as the non-playback UI-notification tool without opening the schema.

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 negative scoping statement ('Doesn't touch playback') tells the agent when this tool is appropriate relative to nowplaying/play/pause/etc., and the description implies this is for user-facing status messaging. However, it never names an explicit alternative or a positive trigger condition, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full behavioral burden and does well: it declares the call is non-mutating, discloses the exact returned snapshot fields, and specifies the idle return shape. It omits what happens when the instance is unreachable or how the target is resolved, which a probe tool would ideally cover.

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 purpose and safety statement are well front-loaded, but the long inline JSON snapshot dump largely restates the output schema that already exists. The opening sentence earns its place; the return-shape enumeration is padding against structured data.

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?

Purpose, safety profile, and idle-state behavior are all covered, and the output schema handles return values, so an agent has enough to call it correctly. The one real gap is failure/unreachable behavior for a tool explicitly framed as a reachability probe.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'instance' and its default fully. The description adds no further semantics (no format, no fallback behavior), which is the baseline 3 case.

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?

States a specific verb and resource ('Report what is playing on the target instance') and adds a second explicit role as a 'reachability and state probe'. This clearly separates it from the mutating siblings play/pause/stop, which an agent can infer without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without changing anything' and the reachability-probe framing give clear context for when to pick this over the play/pause/stop siblings, and the idle case ('{ "state": "stopped" } when idle') tells the agent how to read a null result. No explicit exclusions or named alternatives, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full burden. It discloses the return payload shape and that the action applies to the target instance, but says nothing about what happens when no player is active, whether the call is idempotent, or any permission/auth requirements.

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 the core action before the return detail. Slightly padded by enumerating the returned object's keys, which the output schema already defines.

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?

An output schema exists, so spelling out the snapshot keys is partly redundant, and the behavioral side of a mutating player control (idle-player errors, idempotency) is left uncovered. Adequate but incomplete for a no-annotation mutation 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?

Only one optional parameter and schema description coverage is 100%, so the schema already documents the default-instance behavior. The description adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb and resource ('pause the active player on the target instance'), which is precise and clearly distinct from the adjacent play and stop siblings. It does not explicitly contrast itself with stop/skipnext, but the action is unambiguous without opening the schema.

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?

There is no when-to-use guidance, no mention of prerequisites, and no naming of alternatives such as stop versus pause. The usage is only inferable from the name and the phrase 'pause the active player'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

No annotations are provided, so the description carries the full behavioral burden: it discloses the no-op behavior when nothing is loaded and the exact return snapshot shape, which is real context beyond the schema. It does not mention permission/auth requirements or error conditions, leaving a small gap for a state-changing 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?

Front-loads the core action, then the constraint, then the alternative, then the return shape, in three compact sentences with no filler. Every clause 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 one-optional-parameter tool with an output schema and no annotations, the description covers action, exclusion, alternative, and return structure. Only auth/permission or failure behavior is unaddressed, which is minor given the tool's simplicity.

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?

One optional parameter with 100% schema description coverage, so the schema already explains the 'instance' default behavior. The description adds nothing about the instance parameter, which is the expected baseline when the schema does the heavy lifting.

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?

States a specific verb (resume playback) on a specific resource (Kodi remote) and narrows the scope to 'paused playback only'. It explicitly names the sibling it is not (playfile) and the situation where it is a no-op, so an agent can distinguish it from pause/stop/playfile without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not ('it cannot start new content (with nothing loaded it is a no-op)') and names the correct alternative for that case ('use playfile to start something'). This is the full when/when-not/alternative triad.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full behavioral burden and does reasonably well: it discloses auto player selection (Player.Open), broad path reach, and that a missing-on-disk file surfaces as an error. It omits auth/instance-scoping behavior and any side effects on current playback, keeping it short of a 5.

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?

Front-loads the core action and stays in one dense paragraph with little waste. The returned-state enumeration is arguably redundant given an output schema exists, making it slightly longer than needed.

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 purpose, path scope, error behavior, and playback side effect, which is sufficient for a no-annotation mutation-style tool. Since an output schema exists, the embedded state-snapshot description is extra rather than necessary, and instance/auth behavior is left unaddressed.

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 baseline is 3, but the description adds real meaning for `file` by tying it to `searchmedia` output paths and the in-library-or-not scope. It says nothing extra about `instance` or `fullscreenaudio`, which remain schema-only.

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?

States a specific verb (play) and resource (one file by path), and explicitly frames the input as a `searchmedia` result's `file`, which differentiates it from siblings like `play` and `playfile_with_audio_and_subtitle`. An agent can identify what this does without opening the schema.

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?

Gives concrete context (use a path from `searchmedia`, any reachable path in-library or not) and notes the stale-entry error case, but never names the alternative sibling `playfile_with_audio_and_subtitle` or states when NOT to use this tool. Clear condition, no explicit exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the burden and does well: it discloses the timing behavior ("once it starts"), the argument constraint, the "Video only" limitation, and that it returns a player-state snapshot. It stops short of covering error behavior or what happens to current playback, but the core behavioral profile is present.

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?

Front-loaded with the action, then the constraints and routing in dense em-dash clauses. Every sentence carries information, though the audio/subtitle index wording is slightly repetitive with the schema.

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 4-param tool with full schema coverage and an output schema, the description supplies everything the schema does not: timing, sibling routing, and the required-argument rule. An agent can call it correctly without opening anything else.

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 every parameter including the "off"-vs-omit distinction. The description reinforces the semantics and cross-references audio_and_subtitle_info for index values, but adds little beyond the schema, matching the baseline.

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?

States a specific verb+resource+scope: play a video file by path while selecting its audio track and/or subtitle. It explicitly positions itself against siblings, calling itself the "when starting playback" partner of set_audio_and_subtitle and routing to playfile when no track selection is needed.

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?

Gives an explicit usage rule: "Give at least one of audio/subtitle (else use playfile)", and clarifies the timing distinction vs set_audio_and_subtitle. It also states a scope constraint ("Video only"), so an agent knows when not to reach for it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full burden and does so: it discloses the prerequisite that playback must be active, the refusal of stale/missing-file entries, and that the return is an unchanged player-state snapshot. These are exactly the behavioral traits an agent needs and none are covered by structured 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?

Front-loads the core action, then the input forms, constraints, and return value in a compact flow. Dense and slightly packed but nearly every clause 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 an output schema exists, the description needn't detail return values, yet it still notes the snapshot behavior. Combined with preconditions and input guidance, an agent has everything needed to call it 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%, so the schema already documents all five parameters including the id/file exclusivity and next semantics. The description reinforces the id-vs-file forms and adds the cross-parameter note that type must match the playing queue, but mostly restates schema content, so baseline 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?

States a specific verb (queue) and resource (an item behind the one now playing) with the playback scope spelled out. It distinguishes itself from siblings like play/playfile by describing continuous-queue semantics rather than immediate playback.

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?

Explicitly states the precondition ('Something must already be playing (start with play/playfile)') and names the alternative tools to use first. It also explains that the item can come from a searchmedia row, tying it to the sibling that produces inputs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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

No annotations are provided, so the description carries the full burden and does so well: it discloses paging via limit/offset, a total count, truncation, the full return envelope, and that song-matched rows carry no resolved container while library-wide person matches carry showtitle. It doesn't state read-only-ness explicitly or discuss result ordering, but the read semantics of 'search' are effectively unambiguous.

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?

Purpose is front-loaded in the first clause, followed by parameter routing and the return shape. It is dense but appropriately sized for a 13-parameter tool; the only waste is that the `episodetitle` and `song` explanations restate the schema param descriptions nearly verbatim.

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 13-param search with an output schema, the description covers every meaningful axis: media kinds, paging, the container-vs-item distinction, the sibling escape hatch, and cross-parameter combinations. The return-shape sketch is technically redundant given the output schema, but nothing an agent needs to call it correctly is missing.

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 baseline is 3; the description earns above it by disambiguating the two most confusable parameters ('For music, title means the ALBUM name; match a song by its own title with the `song` arg') and by mapping actor/director to cast vs per-episode matching. Support is largely duplicative of the schema, which keeps it at 4 rather than 5.

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?

States a specific verb and resource ('Find playable files by name: music/tv-show/movie'), names the leaf-file granularity, paging and total count. It also explicitly carves out the sibling boundary: 'Finds media items only — for people lookups ... use `contributors`.' An agent can distinguish this from every sibling without opening the schema.

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?

Gives explicit when-to-use routing: `song` for a track by its own title, `title` for the album/show/movie container, `episodetitle` for an episode by name, and `contributors` for people. The 'play Hey Jude needs no artist' example resolves a real ambiguity an agent would otherwise get wrong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full burden. It does disclose useful behavior: the tool returns a player-state snapshot, "off" differs from omitting the argument, and at least one argument is required. It does not state that this is a live mutation, that something must be playing, or how errors surface — meaningful gaps for an unannotated mutation 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?

One dense but tightly ordered paragraph: action, then parameter semantics, then the omit/require rule, then the return. No sentence is wasted.

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?

An output schema exists, so the brief note about returning a player-state snapshot is sufficient. The main missing piece is the precondition that a video must be playing and how failures are reported, which matters for a three-parameter live-mutation 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%, so the baseline is 3, but the description adds real meaning: it ties both indices to audio_and_subtitle_info, explains the `off` string, and introduces the 'give at least one' constraint that the schema does not express (0 required 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 gives a specific verb+resource: switching the audio track and/or subtitle of the video currently playing on a target instance. It reads clearly against siblings like audio_and_subtitle_info (which supplies the indices) and playfile_with_audio_and_subtitle (which sets streams at playback start), though neither sibling is named.

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 supplies the operative prerequisite — use the `index` values from audio_and_subtitle_info — and states the argument rules (omit to leave unchanged, give at least one). There is no explicit when-not or named alternative for setting streams at playback time, so it stops short of the top mark.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full behavioral burden and does disclose the key edge case (no-op when nothing is loaded) and the remote-keypress semantics, plus what is returned. It does not cover failure modes, permissions, or whether the skip is queued/instantaneous, leaving some behavioral gaps.

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 opening sentence is front-loaded and dense with the essential semantics. The closing enumeration of the player-state snapshot fields is largely redundant given an output schema exists, so it does not fully earn 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 single-optional-parameter remote-key tool with an output schema, the definition covers purpose, edge case, and invocation semantics adequately. Return values need not be described since an output schema exists, though auth/permission expectations are left unstated.

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 single optional 'instance' parameter is fully documented in the schema, so the description adds no parameter meaning. This is the baseline case where the schema does the work.

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?

States a specific verb ('advance to the next item') and resource (active player's playlist/chapter), and the 'Skip Next' framing plus 'next track/chapter' immediately distinguishes it from the sibling skipprevious and from play/queue. An agent can route to it without 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?

It gives clear context ('A remote keypress, not a player command; with nothing loaded it is a no-op'), which tells the agent this is a remote-control style action rather than a command that loads media. It never explicitly names alternatives such as skipprevious or play, so the when-not guidance stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full burden, and it does well: it discloses the Kodi-specific restart-vs-previous behavior, the remote-keypress (not API command) semantics, and the no-op case when nothing is loaded. It stops short of mentioning permissions, error conditions, or whether the keypress is queued/async.

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 lead sentence is well front-loaded with the action and target. However, the trailing sentence dumps the full player-state snapshot field list, which duplicates the output schema and consumes a large share of the text without adding selection-relevant value.

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?

An output schema exists, so the description needn't explain return values, though it does anyway. For a single-optional-param remote-control tool, the description covers behavior, edge case (no-op), and effect sufficiently; only permission/error context is absent.

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 is only one optional parameter ('instance') and schema description coverage is 100%, so the schema already documents it fully. The description adds nothing about instance targeting or default-instance behavior beyond what the schema states, which is the expected baseline here.

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 gives a concrete verb+resource ('Press Skip Previous ... on the Kodi remote') and clarifies the exact effect: go to the previous playlist item, or restart the current one. It also distinguishes itself from the play/pause/stop family by stating it is 'a remote keypress, not a player command,' though it never names the closest sibling (skipnext) directly.

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?

Usage context is implied rather than stated: the agent can infer it is the tool to call when it wants to go backwards, and the no-op condition ('with nothing loaded') is useful. However, no explicit when-to-use guidance or alternative selection (e.g., skipnext vs this tool, or nowplaying to inspect state) is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

With no annotations, the description carries the full burden and does disclose the important non-obvious side effect: the playlist is cleared so queued items don't linger, which matters because stop is more disruptive than pause. It omits permission/auth requirements and error behavior, so it isn't fully transparent.

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 tight sentences, front-loaded with the action and then the side effect. The trailing return-value sentence is largely redundant given the output schema exists, which is the only real waste.

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 single-optional-param tool with a 100%-covered schema and an output schema, the description covers the action and the destructive playlist-clearing behavior. It does not need to explain return values, and the lack of annotations is partly compensated by the stated side 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?

There is only one optional parameter and schema coverage is 100%, so the schema already documents `instance` and its default. The description adds only the phrase 'target instance', which is marginal beyond the structured field.

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?

States a specific verb and resource — stop the active player on the target instance — and names the key side effect (clearing the playing playlist). That effect implicitly distinguishes it from the sibling `pause`, though no sibling is ever named explicitly.

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 'Press Stop on the Kodi remote' framing gives context for when a user would reach for it, but there is no explicit when-to-use, when-not-to-use, or comparison against `pause`/`dropplaylists`, which are the obvious adjacent choices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.