MCP Server Awtrix（mcp-server-awtrix）は、オープンソースのModel Context Protocol (MCP)サーバーであり、宣言型メトリクスオーケストレーターです。AIエージェント（Antigravity、Claude Desktop、Cursor、Cline、AutoGPTなど）に、Awtrix Lightを搭載したUlanzi TC001および互換ピクセルマトリクススマートクロックの完全な制御を提供することを目的としています。
会話型・自律型AIエージェントと物理デスクトップディスプレイを橋渡しし、以下を実現します：
即時エージェントアラート: アドホックなステータスアラート、ビルド失敗通知、タスク完了をピクセル画面にプッシュします。
動的カルーセルアプリ: カスタムライブテレメトリアプリ（サーバーヘルス、SaaSメトリクス、収益カウンター、ビルドステータス）を登録・更新・循環表示します。
宣言的メトリクスポーラー: 専用のPythonスクリプトを書かずに、YAML仕様によるバックグラウンドAPI取得としきい値フォーマットを自動化します。
ハードウェアテレメトリと制御: バッテリーレベルの確認、マトリクス輝度の調整、電源状態の管理、カスタムサウンドキューのトリガー。
Related MCP server: pixoo-mcp-server
スマートピクセルクロック（Awtrix Lightを搭載したUlanzi TC001など）を実行している開発者やパワーユーザーは、現在、外部APIをクエリしてマトリクスアプリを更新するために、断片的でハードコードされたPythonまたはBashのcronスクリプトを書いています。
AIコーディングエージェントを扱う場合：
エージェントは、すべてのメトリックに対して生の命令コードを生成し、維持する必要があります。
AIエージェントがリアルタイム通知を送信したり、ディスプレイのライフサイクルを管理したりするための標準化されたツールセットがありません。
シークレット管理はエラーが発生しやすく、AIプロンプトやログでのAPIキー漏洩のリスクがあります。
マルチセグメントテキストフォーマットとピクセルアイコンのためのネイティブなフォールバックや検証はありません。
ネイティブMCPインターフェース: 通知、カスタムアプリ、デバイス管理、プレビューのための堅牢なツールを公開する標準Model Context Protocolサーバーを提供します。
宣言的テレメトリ: エージェントと人間が、組み込みのテンプレート（Jinja2）としきい値スタイリングを使用して、シンプルなYAMLファイルでメトリックポーリングルールを定義できるようにします。
安全なシークレット分離: .env環境変数置換を使用して、機密の認証情報をプロンプトコンテキストから分離します。
ゼロダウンタイムのホットリロード: サービスを再起動せずに、YAML設定ファイルの変更を自動的に反映します。
信頼性の高いフォールバック: ネットワーク障害、APIレート制限、オフライン表示状態を適切に処理します。
Awtrix Lightファームウェアの置き換え（このツールは公式のAwtrix Light REST/MQTT APIとのみ連携します）。
複雑なマルチモニタータイル同期（焦点は単一またはマルチインスタンスのスタンドアロンピクセルクロックにあります）。
ペルソナ | シナリオ | MCP Server Awtrixがどのように役立つか |
AIコーディングエージェント（例：Antigravity / Cursor） | エージェントが10分間のテストスイートまたは自律タスクをバックグラウンドで完了します。 |
|
DevOps / SREエンジニア | 本番稼働時間、エラーバジェット、またはChecklyの合成テストを監視したい。 |
|
SaaSファウンダー / ビルダー | リアルタイムのMRR、新規ユーザーサインアップ、サポートチケットカウンターをデスクで循環させたい。 | バックエンド管理エンドポイントをクエリする宣言型マルチメトリックアプリを定義します。 |
FR-1: 即時通知（/api/notify）：
カスタムテキスト、マルチセグメントカラーテキスト、アイコンID、サウンド/RTTTL着信音、優先度ホールド、持続時間をサポートします。
FR-2: カスタムカルーセルアプリ（/api/custom）：
ディスプレイループへの名前付きアプリの登録、更新、削除機能。
リッチテキストセグメントフォーマット（[{"t": "FAIL", "c": "FF0000"}, {"t": " (2/10)", "c": "FFFFFF"}]）をサポートします。
FR-3: 宣言型バックグラウンドエンジン：
apps/*.yaml で定義されたポーリングジョブを実行する組み込みスケジューラー（asyncio / apscheduler）。
計算変数、算術演算、条件式をサポートするテンプレートエンジン。
FR-4: デバイス状態とテレメトリ：
バッテリー残量、Wi-Fi RSSI、照度センサー、マトリクス状態、アクティブなアプリをクエリします。
輝度、スリープ/ウェイク状態、トランジションを調整します。
FR-5: ドライランとシミュレーション：
ハードウェア送信前に、正確なレンダリング済みJSONペイロードとカラー検証を返すプレビューツール。
レイテンシ: 直接MCPツール実行は、ローカルネットワーク上で$< 150\text{ms}$以内にAwtrixにディスパッチする必要があります。
耐障害性: オーケストレーターは、アプリを劣化としてマークする前に、指数バックオフで失敗したAPIフェッチを再試行します。
ポータビリティ: 標準Pythonパッケージとしてパッケージ化され、uv/pipxサポート、Dockerコンテナ、スタンドアロンCLIを備えています。
┌──────────────────────────┐
│ AI Client/Host │
│ (Claude / Antigravity / │
│ Cursor / Cline) │
└────────────┬─────────────┘
│
│ stdio / SSE (MCP Protocol)
▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ mcp-server-awtrix │
│ │
│ ┌───────────────────────┐ ┌──────────────────────────────┐ ┌───────────────────┐ │
│ │ MCP Interface │ │ App Orchestrator │ │ Config Watcher │ │
│ │ (Tools / Resources) │ │ (Async Scheduler) │ │ (Hot-Reload) │ │
│ └───────────┬───────────┘ └──────────────┬───────────────┘ └─────────┬─────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Core Engine & Driver │ │
│ │ - Schema Validator (Pydantic) │ │
│ │ - Template & Expression Engine (Jinja2 / JSONPath) │ │
│ │ - Secret Resolver (.env) │ │
│ │ - Awtrix REST / WebSocket Client │ │
│ └──────────────────────────────────────────┬───────────────────────────────────────┘ │
└─────────────────────────────────────────────┼──────────────────────────────────────────┘
│
│ HTTP REST (JSON)
▼
┌──────────────────────────┐
│ Ulanzi TC001 Clock │
│ (Awtrix Light Firmware)│
└──────────────────────────┘MCPインターフェースレイヤー：
stdioおよびSSEを介してModel Context Protocolサーバーエンドポイントを実装します。
厳密なJSONスキーマとAIモデル向けの人間が読めるドキュメントを備えたツールを公開します。
宣言型ポーリングエンジン：
ファイルベースのアプリマニフェストのタスクライフサイクルを管理する非同期ワーカー。
HTTPリクエストを評価し、JSONPath/式を使用してフィールドを抽出し、表示ルールを解決します。
Awtrixドライバー：
デバイス通信、リクエスト重複排除、接続プーリング、エラーリカバリをカプセル化します。
設定とセキュリティレイヤー：
機密トークンを.envに分離します。設定ファイルは${VAR_NAME}構文で変数を参照します。
AIエージェントは以下のMCPツールを実行できます：
awtrix_notify現在のカルーセルを中断して、即時の高優先度通知を画面にプッシュします。
{
"text": "Build Failed: Backend API",
"icon": "10558",
"color": "FF0000",
"duration": 8,
"sound": "alarm",
"rtttl": "beep:d=4,o=5,b=100:16e6,16e6",
"wakeup": true
}awtrix_upsert_appカルーセルループ内の永続的なカスタムアプリを登録または更新します。
{
"name": "app_users",
"text": [
{"t": "1,420", "c": "FFFFFF"},
{"t": " (+42)", "c": "00FF00"}
],
"icon": "2058",
"duration": 5,
"lifetime": 300
}awtrix_delete_appデバイスサイクルからカスタムアプリを削除します。
{
"name": "app_users"
}awtrix_get_device_stateハードウェア統計と現在の運用メトリクスを返します。
応答：
{
"online": true,
"battery": 88,
"charging": true,
"lux": 140,
"temp": 24,
"ram_free": 128440,
"active_app": "app_users",
"brightness": 120
}awtrix_set_settings輝度、マトリクスオン/オフ、トランジション速度などのデバイスパラメータを設定します。
{
"brightness": 80,
"power": true
}awtrix_test_render式を解析し、ハードウェアにプッシュせずにレンダリングされたペイロードを返すドライラン用ヘルパー。
カスタムPythonスクリプトを維持する代わりに、apps/ディレクトリに.yamlマニフェストを配置します。
apps/checkly.yaml
app_id: "checkly"
name: "checkly_status"
enabled: true
interval_seconds: 60
source:
type: "http"
url: "https://api.checklyhq.com/v1/checks"
headers:
Authorization: "Bearer ${CHECKLY_API_KEY}"
X-Checkly-Account: "${CHECKLY_ACCOUNT_ID}"
transform:
total: "len(data)"
failures: "sum(1 for c in data if c.get('hasFailures'))"
degraded: "sum(1 for c in data if c.get('isDegraded') and not c.get('hasFailures'))"
display:
- condition: "failures > 0"
icon: "10558"
notify: true
text:
- { text: "FAIL ", color: "FF0000" }
- { text: "({{failures}}/{{total}})", color: "FFFFFF" }
- condition: "degraded > 0"
icon: "10558"
text:
- { text: "WARN ", color: "FFA500" }
- { text: "({{degraded}}/{{total}})", color: "FFFFFF" }
- condition: "default"
icon: "483"
text:
- { text: "UP ", color: "00FF00" }
- { text: "({{total}})", color: "FFFFFF" }apps/saas_metrics.yaml
app_id: "saas_metrics"
interval_seconds: 120
source:
type: "http"
url: "https://api.example.com/v1/admin/metrics"
headers:
X-API-Secret: "${SAAS_METRICS_API_SECRET}"
sub_apps:
- name: "app_users"
icon: "2058"
text:
- { text: "{{data.users_total}}", color: "FFFFFF" }
- { text: " (+{{data.new_users_last_week}})", color: "00FF00" }
- name: "app_premium"
icon: "5336"
text:
- { text: "{{data.users_premium}}", color: "FFFFFF" }
- { text: " (+{{data.new_users_premium_last_week}})", color: "FFD700" }
- name: "app_orders"
icon: "21072"
text:
- { text: "{{data.orders_total}}", color: "FFFFFF" }
- { text: " (+{{data.new_orders_last_week}})", color: "00FF00" }
- name: "app_support"
icon: "10558"
show_if: "data.tickets_open > 0"
text:
- { text: "{{data.tickets_open}}", color: "FF0000" }Python 3.10以上
Awtrix Light FirmwareがフラッシュされたUlanzi TC001（または互換デバイス）がWi-Fiネットワークに接続されていること。
uv / pipによるローカルセットアップ# Clone the repository
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix
# Copy example environment configuration
cp .env.example .env
# Edit device address and API keys in .env
# AWTRIX_BASE_URL=http://awtrix3.localstdio上でMCPサーバーをローカルで実行します：
# Using uv (recommended)
uv run mcp-server-awtrix
# Or standard pip
pip install -e .
python -m awtrix_mcpDocker Composeを使用して実行します：
# 1. Clone & prepare environment
git clone https://github.com/klodnickik/mcp-server-awtrix.git
cd mcp-server-awtrix
cp .env.example .env
# 2. Start the MCP Server (SSE on port 8000) and Metric Daemon
docker compose up -d
# Or start only the metric poller daemon:
docker compose up -d metric-daemon
# View live logs:
docker compose logs -fmcp_servers.jsonに追加します：
{
"mcpServers": {
"awtrix": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-server-awtrix", "run", "mcp-server-awtrix"],
"env": {
"AWTRIX_BASE_URL": "http://awtrix3.local"
}
}
}
}claude_desktop_config.jsonに追加します：
{
"mcpServers": {
"awtrix": {
"command": "python",
"args": ["-m", "awtrix_mcp"],
"env": {
"AWTRIX_BASE_URL": "http://awtrix3.local"
}
}
}
}Cursor設定 $\rightarrow$ 機能 $\rightarrow$ MCPサーバー $\rightarrow$ サーバーを追加：
名前: awtrix
タイプ: command
コマンド: uv --directory /path/to/mcp-server-awtrix run mcp-server-awtrix
コアMCPツール仕様と設計
宣言型YAMLオーケストレーションスキーマ
非同期HTTPクライアントを備えたFastMCP実装
マトリクスピクセルアート用のライブビジュアルWebプレビュー
MQTTトランスポートレイヤーサポート（RESTの代替オプション）
Home Assistantサービスディスカバリーエクスポート
コントリビューションを歓迎します！機能ディスカッションのためのPRを提出するか、イシューを開いてください。
MITライセンスの下で配布されています。詳細についてはLICENSEを参照してください。
Remove a custom app from the display cycle by name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint and destructiveHint, so the core behavioral safety profile is covered. The description adds context beyond the annotations by specifying exactly what is destroyed or affected: a custom app's presence in the display cycle. No contradiction exists between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the action, target, scope, and parameter mechanism efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required parameter, an output schema is present, and annotations cover idempotency and destructive behavior. The description covers the essential target and parameter. Minor gaps remain around exact-name matching and the precise meaning of 'from the display cycle', but nothing critical is missing for basic 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 0%, and the description only indicates that removal happens 'by name'. This adds meaning beyond the raw schema by relating the 'name' parameter to the custom app identifier, but it does not clarify expected format, uniqueness, or matching behavior. For a single simple parameter, this is adequate but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove'), identifies the exact resource ('a custom app from the display cycle'), and specifies the selection mechanism ('by name'). This clearly distinguishes it from sibling tools like awtrix_upsert_app, which creates or updates an app rather than deleting it.
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 is given about when to use this tool versus alternatives, nor are exclusions or prerequisites mentioned. The intended use is only implied by the tool's name and purpose, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return current AWTRIX hardware metrics: battery, lux, temperature, active app (if available).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral nuance by saying 'current' and 'if available,' signaling that values may change over time and that the active app field can be absent. This is meaningful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence states the action and the list of returned metrics with no filler. The most important scoping word ('current') appears upfront, and the optionality of the active app is handled compactly.
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 no parameters, an output schema present, and annotations covering idempotence/read-only behavior, the description is sufficient for an agent to invoke the tool correctly. It states exactly what hardware metrics will be returned and does not need to cover return formatting because the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description has no parameter burden to carry. The baseline for zero-parameter tools is 4, and there is nothing here that reduces the score; the description instead clarifies what the returned metrics are.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and names the exact resource: current AWTRIX hardware metrics (battery, lux, temperature, active app). It clearly distinguishes this read-only tool from the mutating/action siblings like awtrix_delete_app, awtrix_notify, and awtrix_upsert_app without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is the status/read tool by saying 'Return current...' while all sibling tools are actions or mutations. It does not explicitly state when not to use it, but the context is clear enough that an agent would select this for reading hardware state rather than for changing anything.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push an instant, high-priority notification to the AWTRIX display.
| Name | Required | Description | Default |
|---|---|---|---|
| hold | No | ||
| icon | No | ||
| text | Yes | ||
| color | No | ||
| rtttl | No | ||
| sound | No | ||
| stack | No | ||
| wakeup | No | ||
| duration | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate open-world behavior and non-idempotency, and the description adds that the notification is pushed instantly with high priority. It does not disclose auth needs, rate limits, or stacking/replacement behavior, but it does not contradict the annotations either.
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 that states the essential action and destination with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core call is clear, but the description is minimal for a tool with 9 parameters and several sibling tools. It does not explain optional parameter relationships, duplicate-notification behavior, or when to prefer test_render; the presence of an output schema and annotations softens but does not fill these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no prose about any of the 9 parameters. The schema's names and defaults are somewhat informative, but the description fails to compensate for the coverage gap, such as what 'text' should contain or how icon/color/sound values are formatted.
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 names the action ('Push'), the object ('notification'), and the destination ('AWTRIX display'), and adds the distinguishing 'instant, high-priority' quality. This makes it easy to separate from sibling tools that manage apps, settings, or device state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as awtrix_test_render or awtrix_upsert_app. The phrase 'instant, high-priority' weakly implies a use case, but the agent has to infer the right context from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Configure display brightness, transition animations, and screen power state.
| Name | Required | Description | Default |
|---|---|---|---|
| power | No | ||
| brightness | No | ||
| transitions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the description is not required to restate safety behavior. The description adds a bit of context by listing what settings are affected, but it does not disclose side effects, persistence, or range constraints beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that states the action and the key areas affected. It is front-loaded with the verb and wastes no 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 three-parameter settings tool with an output schema and safety-related annotations, the description is mostly sufficient. It could mention that all parameters are optional and independently updatable, but the schema already conveys that through defaults and nullability.
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 0%, so the description bears the responsibility for explaining parameters. It only paraphrases the property names (brightness, transitions, power) without adding meaning about value ranges, units, null semantics, or the effect of each flag. The schema reveals defaults but little explanatory content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Configure') and clearly identifies the resource (display settings) while naming the three configurable areas: brightness, transition animations, and screen power state. This distinguishes it from the sibling tools like awtrix_notify, awtrix_upsert_app, and awtrix_delete_app.
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 makes the tool's purpose clear enough that an agent can infer when to use it: whenever display-level settings need to be changed. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous given the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and preview a rendered notification/app payload with no hardware side-effects.
| Name | Required | Description | Default |
|---|---|---|---|
| hold | No | ||
| icon | No | ||
| kind | No | app | |
| text | Yes | ||
| color | No | ||
| rtttl | No | ||
| sound | No | ||
| wakeup | No | ||
| rainbow | No | ||
| duration | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true and idempotentHint=true, lowering the burden on the description. The description adds useful specificity by stating 'no hardware side-effects', clarifying what read-only means in this hardware context. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with the action front-loaded and the key safety qualifier stated immediately. Every word earns its place; there is no repetition, filler, or structural waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering safety, an output schema covering return shape, and schema defaults for optional parameters, the description is just barely viable for a minimal call using only the required `text` parameter. However, it lacks guidance on the notification/app distinction and advanced fields, and relies heavily on the provided schema and the agent's domain inference.
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 0%, yet the description provides essentially no parameter-level guidance. It only echoes the 'notification/app payload' concept, which maps to the `kind` enum, but gives no help on ten other parameters, including TextSegment, rtttl, wakeup, rainbow, and color. The description fails to compensate for the missing schema 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 a specific action, 'Validate and preview', applied to a defined resource, 'rendered notification/app payload'. It also distinguishes itself from hardware-affecting siblings by explicitly noting 'no hardware side-effects', leaving no ambiguity about what the tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is a safe preview/validation operation, implying it should be used instead of side-effecting tools like awtrix_notify when testing payloads. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a persistent custom app in the display carousel.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | ||
| name | Yes | ||
| save | No | ||
| text | Yes | ||
| color | No | ||
| repeat | No | ||
| rainbow | No | ||
| duration | No | ||
| lifetime | No | ||
| lifetime_mode | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint and destructiveHint=false, and the description aligns by saying 'create or update' and 'persistent'. It adds useful context about the app living in the display carousel and being persistent, but it does not disclose nuances like the effect of the 'save', 'lifetime', or 'lifetime_mode' parameters on persistence, or whether updating an existing app overwrites prior configuration. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the operation ('Create or update') and immediately clarifies the resource and location ('persistent custom app in the display carousel').
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 (so return values need not be explained), the high parameter count, nested TextSegment definition, and zero parameter descriptions make the overall description insufficient. An agent would not know how to construct a valid 'text' payload, when 'save' should be true, or what lifetime/lifetime_mode mean, so the tool cannot be reliably invoked correctly from the description alone.
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 10 parameters and 0% description coverage, so the description must compensate by explaining parameter meaning. It does not mention a single parameter (name, text, icon, save, color, repeat, rainbow, duration, lifetime, lifetime_mode), leaving the agent to rely solely on schema titles and defaults. This is insufficient for a schema of this complexity.
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 descrip states a specific verb ('Create or update' — an upsert) and a specific resource ('persistent custom app' in the 'display carousel'). This clearly distinguishes it from siblings such as awtrix_delete_app, awtrix_notify, and awtrix_set_settings because it targets custom app lifecycle management, not deletion, notification, or settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys when to use this tool: when the goal is to create or update a persistent custom app in the carousel. It does not explicitly name alternatives or state exclusions, but the context is strong enough that an agent can infer the intended use versus notify or delete siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0awtrix_delete_appawtrix_get_device_stateawtrix_notifyawtrix_set_settingsawtrix_test_renderawtrix_upsert_appScored across 6 tools
Each tool targets a distinct operation: app mutation, instant notification, device state query, settings, and safe preview. notify and test_render are clearly separated by side effects, while upsert_app vs notify is distinguished by persistence and priority.
All tools share the awtrix_ prefix and use snake_case with a mostly verb_noun pattern. awtrix_notify is a minor outlier because it lacks an explicit object, but the overall naming is still predictable and readable.
Six tools cover a focused display-management scope without redundancy. The count is well within the ideal range, and each tool serves a meaningful purpose.
The set covers app create/update/delete, notifications, settings, device state, and safe payload testing. Missing explicit list/get app endpoints are minor gaps that agents can partially work around using the existing app and state tools.
Run your TRMNL ePaper (e-ink) displays from any AI agent: devices, playlists and new screens.
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Display delivery platform for AI agents. Push HTML, dashboards and live data to screens.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
