Coge el mando
Abre la app de Netflix
Busca la serie
Elige la temporada
Elige el episodio
Pulsa play
~30 segundos
stv play netflix "Dark" s1e1~3 segundos
¿No tienes TV? No hay problema. Sin una TV configurada, stv abre el contenido directamente en tu navegador. Netflix, YouTube, Spotify, Disney+ — solo tienes que hacer
pip install stvy listo.
Vibe-coding a las 2am. Claude escribe tu código. Tú le dices que ponga una serie. Y lo hace.
you: play frieren on the living room tv
claude: Playing Frieren s2e8 on Living Room. (3s)
you: bit quieter
claude: Volume → 18.
you: good night
claude: All 3 TVs off.¿Ya tienes stv instalado? Solo dile a Claude:
# Option 1 — just talk (zero config)
"run stv play netflix Frieren s2e8"
# Option 2 — install the Skill for auto-trigger
clawhub install smartest-tv
# now "play Frieren", "good night", "next episode" just work mid-sessionTambién disponible como servidor MCP (21 herramientas) para Claude Code, Codex, Antigravity y otros clientes MCP.
Related MCP server: MCP Roku Control
stv¿Sin subcomando? Obtienes una tarjeta de "Now Playing" y tres acciones contextuales basadas en tu historial de visualización — no un volcado de ayuda con 30 comandos.
$ stv "play dark on netflix" # natural language works
$ stv play "Frieren" # auto-detects platform
$ stv next # continue last show
$ stv stats # → insights¿Entrada desconocida? Recibes una pista amigable, no un error.
Cada comando se renderiza con los colores Catppuccin Mocha, iconos semánticos y una
jerarquía visual real. ¿Prefieres otra paleta? Configura STV_THEME=nord o STV_THEME=gruvbox.
--format json siempre está disponible cuando necesitas pasarlo a jq.
stv play netflix "Dark" s1e1
stv play disney "Percy Jackson" s1e1
stv play prime "The Boys" s1e1
stv play "Frieren" s2e8 # auto-detects platformDi el nombre. stv encuentra el ID, abre la app, inicia la reproducción. Netflix y Apple TV+ se resuelven mediante análisis HTML. Disney+, Max, Prime, Hulu, Paramount+, Peacock, Crunchyroll y todas las plataformas en JustWatch se resuelven mediante su API — sin inicio de sesión, sin clave de API. Omite el nombre de la plataforma y stv detecta automáticamente dónde se está transmitiendo en tu región.
stv cast https://youtu.be/dQw4w
stv cast https://netflix.com/watch/...
stv cast https://open.spotify.com/...Un amigo te envía un enlace. Pégalo. La TV lo reproduce.
stv queue add youtube "Gangnam Style"
stv queue add spotify "Blinding Lights"
stv queue playTodos añaden su elección. La TV reproduce en orden.
stv scene movie-night # volume 20, cinema
stv scene kids # volume 15, Cocomelon
stv scene sleep # rain sounds, auto-offUn comando establece el ambiente.
stv audio play "lo-fi beats"
stv audio volume kitchen 30
stv audio stopPantallas apagadas. Música en todas partes.Sonos gratis.
stv display message "Dinner!"
stv display clock
stv display dashboard "Temp:22°C"Paneles, relojes, señalización.$0/mes.
stv insights
stv screen-time
stv sub-value netflix --cost 17.99¿Vale tu Netflix $18/mes?
stv --all play youtube "lo-fi beats"
stv --group party play netflix "Wed..."
stv --all off # good nightTodas las TVs. A la vez. Incluso amigos remotos.
"Play something chill"
→ tv_recommend → tv_play
→ Playing The Queen's Gambit21 herramientas MCP. Una frase es suficiente.
stv es un servidor MCP. Claude, GPT, Cursor o cualquier cliente MCP puede controlar tu TV con lenguaje natural.
Configuración (una línea):
{
"mcpServers": {
"tv": {
"command": "uvx",
"args": ["stv"]
}
}
}O mediante OpenClaw:
clawhub install smartest-tvLuego solo habla:
You: "I just got home, set up movie night"
Claude: 🎬 Movie night activated.
Volume → 20, cinema mode on.
Based on your history:
1. The Queen's Gambit (Netflix)
2. Ozark (Netflix)
3. Squid Game S2 (Netflix)
You: "Play 1, put a clock on kitchen TV"
Claude: ✓ Playing The Queen's Gambit
✓ Clock on kitchen TVCategoría | Herramienta | Qué hace |
Reproducción |
| Buscar + reproducir por nombre |
| Haz un enlace a cualquier URL | |
| Continuar viendo | |
| Abrir app con ID | |
| Obtener solo el ID del contenido | |
Descubrir |
| Contenido en tendencia |
| Recomendaciones personalizadas | |
Control |
| Encendido/apagado |
| Obtener/establecer/paso/silenciar | |
| Pantalla encendida/apagada | |
| Notificación toast | |
| Estado actual | |
Organizar |
| Cola de reproducción |
| Presets de escena | |
| Historial de visualización | |
Inteligencia |
| Estadísticas de visualización |
| TV como pantalla | |
| Audio multi-sala | |
Multi-TV |
| Reproducir en todas las TVs |
| Listar TVs | |
| Grupos de TVs |
Hora | Qué sucede |
7am |
|
8am |
|
12pm | Un amigo envía un enlace de Netflix → |
5pm |
|
6:30pm |
|
7pm |
|
9pm |
|
10pm |
|
11:30pm |
|
🌙 Piloto automático para dormir
stv audio play "rain" --rooms bedroom
stv scene sleep
stv --all offSonido ambiental, pantalla apagada, temporizador automático, todas las demás TVs apagadas.
🎧 Sonos gratis
stv audio play "lo-fi beats"
stv audio volume kitchen 40
stv audio volume bedroom 15Cada TV es un altavoz. Volumen por habitación. Pantallas apagadas.
💰 Auditoría de suscripciones
stv sub-value netflix --cost 17.99
# → $8.50/hr — consider canceling
stv sub-value youtube --cost 13.99
# → $1.20/hr — good value "Play Dark S1E1"
│
▼
┌─── Resolution ───┐
│ Cache → API → Web │ content_id
│ 0.1s 1s 3s │──────────────▶ 📺 TV plays it
└───────────────────┘ │
Deep link via
LG / Samsung / Roku / AndroidDi un nombre. stv lo resuelve a un ID de contenido, crea un enlace profundo a la app en tu TV. Sin automatización de navegador, sin claves de API, sin dependencia de la nube. Los resultados se guardan en caché para que las reproducciones repetidas sean instantáneas.
pip install stv # LG webOS (default)
pip install "stv[samsung]" # Samsung Tizen
pip install "stv[android]" # Android TV / Fire TV
pip install "stv[all]" # Everythingstv setup # auto-discover + pair your TVCompatible con LG webOS · Samsung Tizen · Android TV / Fire TV · Roku
Añádelo como repositorio personalizado (listado por defecto en revisión: hacs/default#6907):
HACS → ⋮ (top right) → Custom repositories
URL: https://github.com/Hybirdss/smartest-tv
Category: Integration → Add
Then: Install → Restart HA
Settings → Integrations → Add → "Smartest TV" → auto-discovers your TVsAndroid TV / Fire TV: el flujo de configuración muestra un PIN de 6 dígitos en la TV —
introdúcelo en el formulario de emparejamiento para terminar. En HA OS / HA Container configura
STV_CONFIG_DIR=/config/smartest-tv para que el emparejamiento sobreviva a los
reconstrucciones del contenedor. Consulta docs/integrations/home-assistant.md.
Luego úsalo en automatizaciones:
service: media_player.play_media
target:
entity_id: media_player.living_room
data:
media_content_type: stv
media_content_id: "netflix:Frieren:s2e8"Esto hace lo que el media_player.play_media integrado de HA no puede: resolver una serie por nombre y crear un enlace profundo a la app de streaming. El encendido, el volumen y los controles de reproducción también funcionan como entidades estándar de media player de HA.
Integración | Cómo |
Home Assistant | Integración personalizada HACS → |
Claude Code / Cursor | Añade la configuración MCP → |
OpenClaw |
|
cron |
|
Scripts de shell | One-liners de |
Cualquier cliente MCP | 21 herramientas, stdio o HTTP ( |
Configuración para cualquier marca de TV | |
reproducir, transmitir, cola, resolver | |
noche-de-película, niños, dormir, personalizado | |
Multi-TV, fiesta de visualización remota | |
10 combinaciones de funciones potentes | |
MCP para Claude, Cursor, OpenClaw | |
Cada comando y opción | |
Las 21 herramientas con parámetros |
Cada línea de stv está en GitHub: la CLI, los resolvers (Netflix, Apple TV+, YouTube, Spotify, Disney+, Max, Prime Video, Paramount+, Hulu, Peacock, Crunchyroll y más a través de JustWatch), los 4 controladores de TV (LG, Samsung, Roku, Android), la caché, el motor de sincronización, las escenas y las 253 pruebas. Datos de disponibilidad de streaming impulsados por JustWatch.
stv se ejecuta en tu red local. Sin telemetría, sin análisis, sin sincronización en la nube, sin informar a casa sobre lo que ves. No hay posthog, ni amplitude, ni sentry, ni mixpanel — busca en el código fuente.
Una excepción: contribución a la caché comunitaria. Cuando reproduces contenido que no está en la caché local, stv lo resuelve (mediante análisis web) y envía el ID resuelto a una caché comunitaria compartida para que el siguiente usuario obtenga una búsqueda instantánea. Este es el mismo patrón que Wikipedia o un espejo de paquetes: muchas contribuciones pequeñas, anónimas.
Lo que se envía (HTTPS en segundo plano, de disparar y olvidar, nunca bloquea la reproducción):
Nombre de la plataforma (netflix / youtube / spotify)
Slug de contenido (p. ej. frieren)
ID de contenido resuelto (ID de título de Netflix, ID de video de YouTube, URI de Spotify)
Lo que no se envía:
Tu nombre, correo electrónico o cualquier identificador de usuario
Tu dirección IP (la CDN ve una IP de conexión según HTTP estándar, pero el cliente nunca la lee ni la transmite)
Tu historial de visualización o marcas de tiempo de reproducción
La dirección IP de tu TV o información de hardware
Nada sobre con qué frecuencia o cuándo usas stv
Para deshabilitar la contribución a la caché por completo:
export STV_NO_CONTRIBUTE=1Fuente: src/smartest_tv/cache.py — busca _contribute.
211 pruebas. No se necesita TV para ejecutarlas.
pip install -e ".[dev]"
python -m pytest tests/ -vLos controladores de Samsung, Roku y Android TV necesitan pruebas en el mundo real. Si tienes uno, tus comentarios importan.
Contribuciones a la caché · Desarrollo de controladores
Multi-room audio mode — play music with screens off.
Actions: play, stop, volume.
| Name | Required | Description | Default |
|---|---|---|---|
| room | No | Single room name (for "volume" action). | |
| query | No | Music to play (required for "play"). Defaults to YouTube. | |
| rooms | No | List of room/TV names. Omit for all TVs. | |
| action | Yes | "play", "stop", or "volume". | |
| volume | No | Volume level (for "volume" action). | |
| platform | No | "youtube" or "spotify" (for "play"). | youtube |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions 'screens off' and limited actions, but lacks details on side effects, prerequisites, or behavior for multi-room sync. Schema covers parameters but description adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with key information. Efficient and to the point.
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?
Output schema exists, reducing burden. Description covers core functionality but could mention defaults (e.g., omitting rooms plays on all TVs) or additional nuances.
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%. Description adds little beyond stating actions; e.g., 'Actions: play, stop, volume' maps to the action parameter. 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?
Description clearly states the tool's purpose: multi-room audio mode for playing music with screens off. Lists specific actions (play, stop, volume) and distinguishes from siblings like tv_play and tv_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?
No explicit when-to-use or when-not-to-use guidance. Implies use for multi-room audio but does not compare to alternatives among many sibling tv_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cast a Netflix/YouTube/Spotify URL to the TV.
Paste any streaming URL. stv parses the platform and content ID automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Any Netflix, YouTube, or Spotify URL. | |
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It adds 'stv parses the platform and content ID automatically,' which is useful behavioral context. However, it does not disclose error handling, limitations (e.g., supported platforms beyond Netflix/YouTube/Spotify), or side effects (e.g., disrupting current playback).
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, front-loaded with the key action, and adds a concise second sentence for detail. No unnecessary words. Efficient and easy to parse.
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 and presence of an output schema, the description is adequate but lacks contextual completeness. It does not mention prerequisites (e.g., network connectivity, casting support), error scenarios, or runtime behavior. More detail would help an agent 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?
Schema description coverage is 100%, so the baseline is 3. The description adds extra context about auto-parsing for the url parameter, but this is a minor addition. For tv_name, it echoes the schema. Overall, marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Cast a Netflix/YouTube/Spotify URL to the TV.' It uses a specific verb ('Cast') and identifies the resource (streaming URLs) and target (TV). This distinguishes it from sibling tools like tv_play or tv_launch, which have different purposes.
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 (cast streaming URLs) but does not explicitly state when to use this tool over alternatives. It lacks guidance on prerequisites (e.g., TV on same network) or when not to use it. No comparison to sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn the TV into a display — show dashboards, messages, clocks, or any URL.
The TV becomes a smart display. HTML is generated and served locally, then opened in the TV's browser.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Content-specific data: - message: {"text": "Hello!", "bg": "#000", "color": "#fff"} - clock: {"format": "24h"} or {"format": "12h"} - dashboard: {"title": "Home", "cards": [{"label": "Temp", "value": "22°C"}]} - photo: {"urls": ["http://..."], "interval": 5} - iframe: {"url": "https://...", "fullscreen": true} - custom: {"html": "<div>...</div>"} | |
| port | No | Local server port (default 8765). | |
| tv_name | No | Target TV. Omit for default. | |
| content_type | Yes | "message", "clock", "dashboard", "photo", "iframe", or "custom". |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the mechanism (HTML generated and served locally) but does not disclose potential side effects like interrupting current TV usage, error handling, or requirements (TV on/connected).
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, front-loaded with the purpose, and concise. No wasted words; every sentence adds 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?
Given the complexity (multiple content types) and that an output schema exists, the description is fairly complete. It explains the tool's function and mechanism, though it could mention impact on current TV state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with detailed examples for the 'data' parameter. The tool description adds no extra meaning beyond the schema; it just summarizes what content types are supported. 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 tool turns the TV into a display for dashboards, messages, clocks, or any URL. It uses specific verbs and resources, and differentiates from sibling tools like tv_audio or tv_cast.
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 when to use the tool (to display custom content on TV) but does not explicitly state when not to use it or compare with alternatives like tv_cast for streaming or tv_launch for apps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all TV groups and their members.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It only states the function, omitting critical traits like read-only nature, side effects, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no 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 tool's simplicity and the presence of an output schema, the description is minimally adequate but lacks context about what constitutes a 'TV group' or how results are structured.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description adds no parameter info. Per guidelines, baseline is 4 for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and the resource (TV groups and their members). It distinguishes itself from sibling tools like tv_list_tvs and tv_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With 22 sibling tools, explicit context would be helpful but is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show recent play history.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states 'show recent play history'. It omits details like scope, ordering, side effects, or authorization needs, making the tool's behavior opaque.
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 (one sentence), but it sacrifices necessary detail. It is not optimally structured for an agent, lacking front-loaded key 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?
Given the tool has an output schema but no parameter explanation, and given the many sibling tools, the description is too sparse to be complete. It does not leverage the context to aid selection or usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the description does not mention the 'limit' parameter at all, failing to add any meaning beyond the schema definition.
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 shows 'recent play history', which is a specific verb-resource pair. However, it does not distinguish from siblings like 'tv_whats_on' or 'tv_queue' that might also involve recent 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?
No guidance on when to use this tool versus alternatives. The description lacks context on use cases, prerequisites, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get viewing insights, screen time, or subscription value analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | "day", "week", or "month". | week |
| report_type | No | "full" (formatted report), "screen_time", or "sub_value:platform:cost" (e.g. "sub_value:netflix:17.99"). | full |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavioral traits. It implies a read-only operation by saying 'Get', but does not explicitly mention side effects, auth requirements, or other constraints. The parameter hints add minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that earns its place by conveying the core functionality without fluff. However, it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 optional parameters, full schema coverage, and an output schema), the description is adequately complete. It captures the main purpose, though additional context about output format or typical use cases would be helpful.
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 baseline is 3. The description adds no additional meaning beyond the schema, as it only reiterates the report types that are already described in the parameter definitions.
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 provides viewing insights, screen time, or subscription value analysis. It uses a specific verb and resource, but does not distinguish from sibling tools like tv_whats_on or tv_recommend, so it misses a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only states what it does, without any context or exclusions, leaving the agent to infer usage from the name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch an app, optionally with a deep link.
Use tv_play instead if you have a content name (not ID). Use this when you already have the exact content ID.
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | App name (netflix, youtube, spotify) or raw app ID. | |
| tv_name | No | Target TV name. Omit for default TV. | |
| content_id | No | Platform-specific content ID for deep linking. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes core action but lacks details on side effects, prerequisites, or error handling. No annotations are provided to supplement this.
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 that front-load the purpose and pair it with conditional guidance, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (launch app with optional params) and presence of an output schema, the description fully covers what the agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage), and the description adds no new information 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?
Clearly states it launches an app with optional deep link, and distinguishes from tv_play by specifying when to use each based on content identifier type.
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 tells the agent to use tv_play for content names and tv_launch for exact content IDs, providing clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all configured TVs with name, platform, IP, and default status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It describes a read-only listing, but does not explicitly state it is non-destructive or has no side effects. The description is truthful but adds minimal behavioral context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, efficiently stating the action and the data returned. No redundant 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 simple list-all tool with zero parameters and an output schema, the description is fairly complete. It could mention that it returns all TVs without filtering or ordering, but the core functionality is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is effectively 100%. The description adds value by listing the fields returned, which helps the agent understand the output. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all configured TVs and specifies the returned fields (name, platform, IP, default status). It uses a specific verb and resource, distinguishing it from sibling tools like tv_status or tv_power.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it does not mention that this tool is for obtaining an overview, while tv_status might be used for detailed info on a single TV.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play the next episode. Continues from watch history.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Show name. Omit to continue the most recent Netflix show. | |
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits (e.g., immediate playback, side effects). Only states the action without elaboration on what happens or what the output contains.
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 very concise with two sentences, but could be slightly expanded to include usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks prerequisites (e.g., need watch history, target TV) and fails to guide the agent on when this tool is appropriate among 22 siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds minimal context about 'next episode' and 'watch history', but doesn't significantly enhance 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 clearly states it plays the next episode based on watch history, which distinguishes it from general playback tools like tv_play. However, it could explicitly differentiate from tv_recommend or tv_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for continuing a series, but lacks explicit guidance on when to use vs siblings (e.g., vs tv_play) or prerequisites like having watch history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a toast notification on the TV screen.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Text to display. | |
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Show a toast notification', omitting critical details like whether the TV must be powered on, whether it requires an active connection, what happens if the TV is off, or if the tool returns any acknowledgment. This lack of transparency could lead to misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. It contains no redundant words. However, it could benefit from a bit more structure, e.g., separating behavior from parameter hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the presence of an output schema (content unknown), the description should still mention what the tool returns (e.g., success/failure, error conditions) and any prerequisites (e.g., TV must be on). The current description is insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions. The tool description adds nothing beyond the schema: it does not clarify the format or constraints of the message, nor the behavior when tv_name is omitted. Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Show') and the resource ('toast notification on the TV screen'). It distinguishes this tool from siblings like tv_audio or tv_launch, which have different purposes. However, it could be more specific about what a toast notification entails (e.g., duration, 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 no guidance on when to use this tool versus alternatives. For example, it does not indicate whether this is for brief messages vs. tv_display for persistent content, or when to use tv_notify over tv_state notifications. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find content by name and play it on TV.
This is the primary tool. Resolves the content ID automatically, then deep-links into the app on your TV.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Content name (e.g. "Stranger Things", "baby shark", "Ye White Lines"). | |
| season | No | Season number (Netflix series only). | |
| episode | No | Episode number (Netflix series only). | |
| tv_name | No | Target TV name. Omit for default TV. | |
| platform | Yes | "netflix", "youtube", or "spotify". | |
| title_id | No | Netflix title ID if already known (skips search). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by disclosing automatic content ID resolution and deep-linking behavior. However, it omits details on error handling or prerequisites.
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 key purpose, no redundant information. Efficient and well-structured.
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 covers the core function and key behavior. Lacks mention of error responses or supported platforms beyond what schema provides, but adequate for a play 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 baseline 3 is appropriate. The description does not add parameter meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find content by name and play it on TV.' It distinguishes itself as 'the primary tool' among siblings, with a specific verb and resource.
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 claims it is the 'primary tool' but does not explicitly state when to use it versus alternatives like tv_cast or tv_queue. No exclusions or when-not-to-use guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn TV on or off.
| Name | Required | Description | Default |
|---|---|---|---|
| on | Yes | True = turn on, False = turn off. | |
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing behavioral traits such as idempotency, error states, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveying the essential information without unnecessary words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple power-on/off command, the description is adequate given that an output schema exists. However, it could be more explicit about behavior (e.g., toggle vs set).
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 parameters are well-documented in the schema. The description adds no additional meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Turn' and resource 'TV' with clearly defined states 'on or off'. It distinguishes itself from sibling tools like tv_audio, tv_cast, etc., which deal with different functionalities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage the play queue. Actions: add, show, play, skip, clear.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Required for "add". Content name. | |
| action | Yes | "add", "show", "play", "skip", or "clear". | |
| season | No | For "add" — Netflix season number. | |
| episode | No | For "add" — Netflix episode number. | |
| tv_name | No | For "play" — target TV. | |
| platform | No | Required for "add". netflix/youtube/spotify. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but does not disclose behavioral traits such as side effects, state changes, or required permissions. The brief action list is insufficient for understanding what each action does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a single sentence and bullet-like list of actions. Every word is purposeful, and the structure is clear and easy to scan.
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?
Despite the output schema and full parameter descriptions in the schema, the overall description is too brief for a tool with multiple actions and 6 parameters. It fails to explain how actions relate to parameters or what the tool returns.
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 no additional parameter context beyond listing action names, which is adequate but not enhanced.
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 indicates the tool manages a play queue and lists the supported actions (add, show, play, skip, clear), distinguishing it from sibling tools like tv_play that likely handle direct 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?
No guidance is provided on when to use this tool versus alternatives (e.g., tv_play for direct play, or other queue-like tools). The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get personalized recommendations based on watch history + trending.
| Name | Required | Description | Default |
|---|---|---|---|
| mood | No | "chill", "action", "kids", "random", or omit for auto. | |
| limit | No | Number of recommendations (default 5). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 only states that recommendations are based on watch history and trending, but does not disclose whether the tool is read-only, requires authentication, or any side effects. This is insufficient for a tool that likely accesses user data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, which is very concise. No filler content. However, it could include additional context without becoming verbose, so it loses a point for not being more 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?
Given the presence of an output schema (not shown), the description does not need to explain return values. Parameters are well-documented in the schema. However, behavioral context (e.g., safety, data usage) is missing, making the description adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (mood, limit) with descriptions. The description does not add meaning beyond what the schema already provides, so it meets the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get personalized recommendations based on watch history + trending.' It uses a specific verb and resource, and the basis (watch history + trending) differentiates it from sibling tools like tv_whats_on (current programming) and tv_next (next episode).
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 context (personalized recommendations), but does not explicitly state when to use or not use this tool over alternatives. Given the sibling tools are numerous and diverse, the context is clear enough for an agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a content name to its platform ID without playing.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Content name. | |
| season | No | Season number (Netflix). | |
| episode | No | Episode number (Netflix). | |
| platform | Yes | netflix, youtube, or spotify. | |
| title_id | No | Netflix title ID if known. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only notes that the tool does not play content, but fails to disclose other behavioral traits like whether it is read-only, auth requirements, or error handling behavior. The description is very minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. However, it is very concise to the point of being slightly underspecified, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no annotations, and an output schema present, the description lacks context for when to use the optional parameters (season, episode, title_id) and does not explain the purpose of resolving to a platform ID. The description is insufficient for an effective agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters. The description adds no additional meaning or context beyond what the schema provides, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('resolve a content name to its platform ID') and distinguishes from sibling tools like tv_play by noting 'without playing'. This provides a specific verb and resource, but the term 'platform ID' could be further clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, such as when to use tv_play or other related tools. No when-not or explicit context is given, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run or list scene presets. Built-in: movie-night, kids, sleep, music.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Scene name (required for "run"). | |
| action | No | "list" or "run". | list |
| tv_name | No | Target TV (for "run"). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions built-in scenes but omits details like error handling, required TV state, or response format. The description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently states the core purpose and key examples. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and an output schema, the description is too brief. It lacks details on the response format, error scenarios, and behavioral constraints. For a tool with many siblings, it should provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds the list of built-in scenes, which provides context beyond the schema. 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 tool's purpose: 'Run or list scene presets.' It includes specific built-in examples (movie-night, kids, sleep, music), distinguishing it from sibling tools like tv_power or tv_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 provides no guidance on when to list vs. run, when to use this tool over alternatives, or any prerequisites. The schema implies list is default but no explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn screen on or off (audio continues when off).
| Name | Required | Description | Default |
|---|---|---|---|
| on | Yes | True = screen on, False = screen off (audio continues). | |
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses one key behavior (audio continues when off) but lacks details on permissions, side effects, or other operational 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 a single, concise sentence that conveys the core action and a behavioral note. No wasted words; front-loaded with the verb-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 low complexity (2 parameters, no enums, output schema present), the description covers the essential purpose and one behavioral effect. It is likely sufficient for the AI to use correctly, though additional detail on when to use vs. siblings would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's own parameter descriptions (e.g., 'True = screen on' is already in the schema). No additional semantics are contributed.
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-resource: 'Turn screen on or off', and distinguishes from siblings like tv_power (controls entire power) and tv_audio (controls audio) by specifying that audio continues when the screen is off.
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 a use case (keeping audio while turning off screen) but does not explicitly state when to use this vs. alternatives like tv_power or tv_audio. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get unified live TV state: playback, volume, input, power.
Returns a single snapshot for agent branching. Fields the target driver cannot supply are returned as None.
| Name | Required | Description | Default |
|---|---|---|---|
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that unsupplied fields are returned as None and that it returns a snapshot. This adds some behavioral context, but lacks details on authentication, rate limits, or side effects, which are important for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states purpose and key fields, the second adds behavioral detail and usage context. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, existence of an output schema, and no nested objects, the description covers all essential aspects: what data is returned (playback, volume, input, power), that it's a snapshot, and how missing fields are handled. Fully adequate for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description ('Target TV name. Omit for default TV.'). The tool description does not add further meaning about the parameter beyond hinting at the output, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'unified live TV state' and lists specific fields (playback, volume, input, power). It distinguishes from siblings like tv_volume or tv_power by emphasizing it's a single composite snapshot, and mentions 'agent branching' to differentiate from tv_state_watch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by saying 'Returns a single snapshot for agent branching,' which implies one-off state retrieval for decision-making. However, it does not explicitly state when to use this tool versus alternatives like tv_state_watch for continuous monitoring, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stream tv_state snapshots via progress notifications.
Emits count progress updates spaced interval seconds apart,
then returns the final snapshot. Default is 1 minute of watching.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of snapshots to emit (default 12). | |
| tv_name | No | Target TV name. Omit for default TV. | |
| interval | No | Seconds between snapshots (default 5). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: streaming via progress notifications, configurable count and interval, final snapshot return, and default duration. Since no annotations are provided, this is sufficient.
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 (two sentences), front-loads the core action, and is structured logically. It could be slightly more structured with bullet points, but remains effective.
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 3 parameters with full schema coverage and an output schema existing, the description adequately covers the tool's functionality. It explains the streaming behavior and defaults, which is enough for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions. The description adds context about the default behavior ('Default is 1 minute of watching'), but does not significantly enhance meaning 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 states the tool streams tv_state snapshots via progress notifications, specifying the verb 'stream' and the resource 'tv_state snapshots'. It uniquely identifies the tool's function among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for observing state over time with defaults, but does not explicitly state when to use this tool versus alternatives like tv_state (single snapshot) or other TV tools. No guidance on 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.
Get TV status: current app, volume, mute, model, firmware.
| Name | Required | Description | Default |
|---|---|---|---|
| tv_name | No | Target TV name. Omit for default TV. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly lists the returned fields, making the tool's behavior clear. It implies a read-only operation without side effects. However, with no annotations, the description could be more explicit about non-destructiveness and any prerequisites, though for a simple getter this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, front-loading the action and key fields. It contains no filler and every word adds 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?
Given the tool's simplicity (one optional parameter, output schema present), the description covers the essential information. It could be slightly more complete by mentioning that it returns a snapshot (vs. watch tools), but overall it's sufficient for an agent to use 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% (parameter 'tv_name' is fully documented in the input schema). The description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Get' and specifies the resource 'TV status', followed by a concise list of fields (current app, volume, mute, model, firmware). This clearly distinguishes it from sibling tools like tv_volume or tv_whats_on, which target specific subsets.
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 is provided. The description implies it is the general status snapshot, but fails to mention that more specific tools (e.g., tv_volume, tv_whats_on) might be preferred for individual attributes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Play content on multiple TVs simultaneously (party mode).
Resolves once, launches on all targets via asyncio.gather.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | TV group name (e.g. "party"). | |
| query | Yes | Content name. | |
| season | No | Netflix season number. | |
| episode | No | Netflix episode number. | |
| platform | Yes | netflix, youtube, or spotify. | |
| title_id | No | Netflix title ID if known. | |
| tv_names | No | List of TV names. Or use group. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that it resolves once and launches via asyncio.gather (async behavior), but it does not specify error handling, waiting behavior, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded purpose then technical detail. Very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given good schema coverage and an output schema, the description covers the core functionality. However, missing usage guidelines relative to siblings is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for each parameter. The tool description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Play content on multiple TVs simultaneously (party mode)', which is a specific verb+resource+scope. It distinguishes from siblings like tv_launch and tv_play by emphasizing multi-TV sync.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for broadcasting to multiple TVs but does not explicitly state when to use this tool vs alternatives like tv_launch or tv_cast. No when-not or alternative names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get or set volume, step up/down, or toggle mute. All in one tool.
No args: returns current volume + mute status
level=25: set volume to 25
direction="up"/"down": step volume
mute=True/False/None: mute, unmute, or toggle
| Name | Required | Description | Default |
|---|---|---|---|
| mute | No | True=mute, False=unmute, None=toggle. | |
| level | No | Volume level 0-100. | |
| tv_name | No | Target TV name. Omit for default TV. | |
| direction | No | "up" or "down" for one step. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses both read behavior (no args returns current volume+mute) and write behavior (setting, stepping, muting). It does not mention side effects or permissions, but the tool's simple nature makes this sufficient.
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 (3 sentences plus bullet examples). It front-loads the main purpose. Every line adds value, though the bullet list could be more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and an output schema (not shown). The description covers the return for no args but does not explain behavior when multiple parameters are combined (e.g., setting level and direction together). For a simple tool, it is adequate but not fully comprehensive.
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 value by showing usage patterns (e.g., 'level=25') and explaining the mute parameter's behavior (True=mute, False=unmute, None=toggle), which clarifies the null meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get or set volume, step up/down, or toggle mute.' It uses specific verbs (get, set, step, toggle) and resource (volume), distinguishing it from sibling tools like tv_audio or tv_power.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage patterns for each parameter (e.g., 'level=25: set volume to 25', 'direction="up"/"down": step volume', 'mute=True/False/None'). It does not explicitly state when not to use the tool or suggest alternatives, but the examples cover common use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show trending content on Netflix and/or YouTube.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results per platform (default 10). | |
| platform | No | "netflix", "youtube", or omit for both. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It correctly indicates this is a read-only operation (showing content), but does not mention authentication needs, rate limits, or what happens with invalid platform values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no waste. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are covered. However, the description does not mention the nature of the output (e.g., list of titles, scores) or any limitations like pagination, making it marginally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already defines limit and platform. The description adds context ('trending content on Netflix and/or YouTube') but does not enhance the meaning of the parameters 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 action 'Show' and the resource 'trending content on Netflix and/or YouTube', which distinctly separates it from sibling tools like tv_audio or tv_power.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for discovering trending content on streaming platforms, but lacks explicit guidance on when to use or not use this tool compared to alternatives. However, sibling tools are so different that it's reasonably clear.
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.
v1.0.2tv_audiotv_casttv_displaytv_groupstv_historytv_insightstv_launchtv_list_tvstv_nexttv_notifytv_playtv_powertv_queuetv_recommendtv_resolvetv_scenetv_screentv_statetv_state_watchtv_statustv_synctv_volumetv_whats_onv0.3.0tv_audiotv_casttv_displaytv_groupstv_historytv_insightstv_launchtv_list_tvstv_nexttv_notifytv_playtv_powertv_queuetv_recommendtv_resolvetv_scenetv_screentv_statustv_synctv_volumetv_whats_onv0.1.0tv_audiotv_casttv_displaytv_groupstv_historytv_insightstv_launchtv_list_tvstv_nexttv_notifytv_playtv_powertv_queuetv_recommendtv_resolvetv_scenetv_screentv_statustv_synctv_volumetv_whats_onScored across 23 tools
Most tools have clearly distinct purposes. Some overlap exists between tv_launch/tv_play and tv_state/tv_status/tv_state_watch, but descriptions clarify the specific use cases (ID-based vs name-based, snapshot vs streaming).
All tools use the 'tv_' prefix followed by a verb_noun pattern (e.g., tv_play, tv_notify, tv_list_tvs). The naming is entirely consistent in style (snake_case) and predictable, making it easy for agents to infer functionality.
With 23 tools, the surface is robust but slightly heavy for a TV control server. Each tool serves a distinct function, and the count is justifiable given the breadth of features (playback, queue, sync, recommendations, etc.). Could be trimmed by combining some state tools, but not excessive.
The tool set covers most core TV operations: power, volume, playback, queue, casting, display, notifications, groups, and insights. Missing are input switching, settings management, or account-related operations, but these are minor gaps for a streaming-focused TV server.
Control Android TV from any AI. 38 MCP tools: playback, recap, recommend, smart-home, schedules.
Manage digital signage screens, playlists and media from your AI assistant.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
