Retrieve TRMNL playlist items, optionally filtered by device ID, with plugin names, visibility, row order, group IDs, and render timestamps.
Read TRMNL playlist items, optionally for one numeric device_id. Returns plugin names, visibility, row_order, group IDs and render timestamps in API order. Does not fetch images or custom durations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| device_id | No |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds valuable disclosure about return fields (plugin names, visibility, row_order, group IDs, render timestamps) and explicitly notes that images and custom durations are not fetched. This goes beyond annotations and helps manage agent expectations.
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 succinct sentences. The purpose and key scoping detail (optional device_id) are front-loaded, and the exclusions (images/durations) are stated in a single trailing clause. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with three optional parameters and no output schema, the description should explain pagination (limit/offset) and default behavior. It mentions return fields but not the response structure or how parameters affect results. Given the annotations cover safety, the description is partially complete but leaves parameter semantics and expected output shape to 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%, so the description must explain parameters. It only mentions that device_id is optional and numeric, but provides no explanation of limit or offset, their defaults, or their effects. The agent cannot infer pagination behavior from the description, and the schema alone doesn't carry semantic guidance. This is a significant gap.
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 'Read' and resource 'TRMNL playlist items', and specifies optional filtering by device_id. It is distinct from siblings like list_devices (different resource) and mutation tools, but it does not explicitly name or contrast a sibling, so it falls short of a 5.
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 this tool is for reading playlist items and mentions optional device_id filtering, but provides no explicit guidance on when to use it versus alternatives like get_playlist_item_schedule or the mutation tools. There is no when-not-to-use context, so it stops at clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.