拿起遥控器
打开 Netflix 应用
搜索节目
选择季度
选择单集
按下播放
约 30 秒
stv play netflix "Dark" s1e1约 3 秒
没有电视？没问题。 没有配置电视时，stv 会直接在浏览器中打开内容。 Netflix、YouTube、Spotify、Disney+ — 只需
pip install stv即可开始。
凌晨 2 点 Vibe 编程。Claude 写你的代码。你告诉它放个节目。它照做。
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.已经装好 stv？直接告诉 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-session也可作为 MCP 服务器（21 个工具）用于 Claude Code、Codex、Antigravity 及其他 MCP 客户端。
Related MCP server: MCP Roku Control
stv没有子命令？你会得到一张“正在播放”卡片，以及基于观看历史的三个上下文相关下一步操作—而不是一份 30 条命令的帮助信息堆砌。
$ stv "play dark on netflix" # natural language works
$ stv play "Frieren" # auto-detects platform
$ stv next # continue last show
$ stv stats # → insights输入无法识别？你会得到友好的提示，而不是报错。
每条命令都以 Catppuccin Mocha 配色、语义图标和真正的视觉层级渲染。更喜欢其他配色？设置 STV_THEME=nord 或 STV_THEME=gruvbox。
--format json 始终可用，以便你通过管道传给 jq。
stv play netflix "Dark" s1e1
stv play disney "Percy Jackson" s1e1
stv play prime "The Boys" s1e1
stv play "Frieren" s2e8 # auto-detects platform说出名称。stv 会找到 ID、打开应用、开始播放。Netflix 和 Apple TV+ 通过解析 HTML 实现；Disney+、Max、Prime、Hulu、Paramount+、Peacock、Crunchyroll 以及 JustWatch 上的所有平台 通过它们的 API 实现—无需登录，无需 API 密钥。省略平台名称时，stv 会自动检测它在你的地区由哪个平台提供流媒体播放。
stv cast https://youtu.be/dQw4w
stv cast https://netflix.com/watch/...
stv cast https://open.spotify.com/...朋友发来链接。粘贴进去。电视上播放。
stv queue add youtube "Gangnam Style"
stv queue add spotify "Blinding Lights"
stv queue play每个人添加自己的选择。电视按顺序播放。
stv scene movie-night # volume 20, cinema
stv scene kids # volume 15, Cocomelon
stv scene sleep # rain sounds, auto-off一条命令搞定氛围。
stv audio play "lo-fi beats"
stv audio volume kitchen 30
stv audio stop屏幕关闭。音乐无处不在。免费 Sonos。
stv display message "Dinner!"
stv display clock
stv display dashboard "Temp:22°C"仪表盘、时钟、标牌。$0/月。
stv insights
stv screen-time
stv sub-value netflix --cost 17.99你的 Netflix 每月 18 美元值不值？
stv --all play youtube "lo-fi beats"
stv --group party play netflix "Wed..."
stv --all off # good night每台电视同时播放。远方的朋友也能同步。
"Play something chill"
→ tv_recommend → tv_play
→ Playing The Queen's Gambit21 个 MCP 工具。一句话就够。
stv 是一个 MCP 服务器。Claude、GPT、Cursor 或任何 MCP 客户端都可以用自然语言控制你的电视。
设置（一行）：
{
"mcpServers": {
"tv": {
"command": "uvx",
"args": ["stv"]
}
}
}或通过 OpenClaw：
clawhub install smartest-tv然后直接说：
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 TV类别 | 工具 | 功能 |
播放 |
| 按名称搜索并播放 |
| 投射任意 URL | |
| 继续观看 | |
| 按 ID 启动应用 | |
| 仅获取内容 ID | |
发现 |
| 热门内容 |
| 个性化推荐 | |
控制 |
| 开/关 |
| 获取/设置/步进/静音 | |
| 屏幕开/关 | |
| Toast 通知 | |
| 当前状态 | |
整理 |
| 播放队列 |
| 场景预设 | |
| 观看历史 | |
智能 |
| 观看统计 |
| 电视作显示屏 | |
| 多房间音频 | |
多电视 |
| 在所有电视上播放 |
| 列出电视 | |
| 电视分组 |
时间 | 发生的事情 |
7am | 在厨房电视上运行 |
8am |
|
12pm | 朋友发来 Netflix 链接 → |
5pm |
|
6:30pm |
|
7pm |
|
9pm |
|
10pm |
|
11:30pm |
|
🌙 睡前自动模式
stv audio play "rain" --rooms bedroom
stv scene sleep
stv --all off环境音、屏幕关闭、自动定时，其他电视全部关闭。
🎧 免费 Sonos
stv audio play "lo-fi beats"
stv audio volume kitchen 40
stv audio volume bedroom 15每台电视都是音箱。按房间调节音量。屏幕关闭。
💰 订阅审计
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 / Android说出名称。stv 会将其解析为内容 ID，并通过深度链接进入你电视上的应用。无需浏览器自动化，无需 API 密钥，不依赖云端。结果会被缓存，因此重复播放立即完成。
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 TV支持 LG webOS · Samsung Tizen · Android TV / Fire TV · Roku
添加为自定义仓库（默认列表审核中：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：设置流程会在电视上显示一个 6 位 PIN——在配对表单中输入它即可完成。在 HA OS / HA Container 中设置 STV_CONFIG_DIR=/config/smartest-tv，这样配对在容器重建后依然有效。参见 docs/integrations/home-assistant.md。
然后在自动化中使用：
service: media_player.play_media
target:
entity_id: media_player.living_room
data:
media_content_type: stv
media_content_id: "netflix:Frieren:s2e8"这能完成 HA 内置 media_player.play_media 做不到的事：按名称解析节目，并深度链接到流媒体应用。电源、音量和播放控制也作为标准的 HA media player 实体正常工作。
集成 | 方式 |
Home Assistant | HACS 自定义集成 → 带内容解析的 |
Claude Code / Cursor | 添加 MCP 配置 → |
OpenClaw |
|
cron |
|
Shell 脚本 |
|
任意 MCP 客户端 | 21 个工具，stdio 或 HTTP（ |
适用于任何电视品牌的设置 | |
play、cast、queue、resolve | |
movie-night、kids、sleep、custom | |
多电视、远程观看派对 | |
10 种强大的功能组合 | |
面向 Claude、Cursor、OpenClaw 的 MCP | |
所有命令和选项 | |
全部 21 个工具及参数 |
stv 的每一行代码都在 GitHub 上 —— CLI、解析器（Netflix、Apple TV+、YouTube、Spotify、Disney+、Max、Prime Video、Paramount+、Hulu、Peacock、Crunchyroll，以及通过 JustWatch 支持的更多平台）、全部 4 个电视驱动（LG、Samsung、Roku、Android）、缓存、同步引擎、场景，以及全部 253 个测试。流媒体可用性数据由 JustWatch 提供。
stv 在你的本地网络上运行。没有遥测、没有分析、没有云同步、不会将你观看的内容回传。没有 posthog、没有 amplitude、没有 sentry、没有 mixpanel —— 去源码里 grep 一下。
一个例外 —— 社区缓存贡献。 当你播放的内容不在本地缓存中时，stv 会解析它（通过网页解析），并将解析出的 ID 提交到共享的社区缓存，这样下一位用户就能立即查询到。这与 Wikipedia 或软件包镜像的模式相同 —— 大量微小的贡献，且都是匿名的。
会发送的内容（后台 HTTPS，发后即忘，绝不会阻塞播放）：
平台名称（netflix / youtube / spotify）
内容 slug（例如 frieren）
解析出的内容 ID（Netflix 标题 ID、YouTube 视频 ID、Spotify URI）
不会发送的内容：
你的姓名、电子邮件或任何用户标识
你的 IP 地址（按照标准 HTTP，CDN 会看到一个连接 IP，但客户端从不读取或传输它）
你的观看历史或播放时间戳
你电视的 IP 地址或硬件信息
任何关于你使用 stv 的频率或时间的信息
要完全禁用缓存贡献：
export STV_NO_CONTRIBUTE=1来源：src/smartest_tv/cache.py —— 搜索 _contribute。
211 个测试。运行它们不需要电视。
pip install -e ".[dev]"
python -m pytest tests/ -vSamsung、Roku 和 Android TV 驱动需要真实环境测试。如果你有其中一台，你的反馈很重要。
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.
