Provides tools for creating, managing, auditing, and optimizing Apple Music playlists, including search, metadata analysis, audio-feature coverage, and track sequencing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@am-mcp Create a playlist named 'Chill Mix' and add 'Blinding Lights' by The Weeknd."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Português do Brasil | Deutsch | Français
Deep playlist curation for Apple Music: describe a feeling, scene, era, tension, or narrative arc; your agent turns it into a catalog-grounded selection whose versions, pacing, and transitions hold together as a listening experience.
Pure Python standard library — no pip install required to run, and no Apple Developer Program
membership needed. Requires Python 3.10+ and works on Windows / macOS / Linux.
The primary interface is the local am-mcp stdio server. The language model already running in
your MCP client interprets the brief and chooses candidates; this project searches the Apple Music
catalog, resolves exact tracks, and performs account operations. There is no bundled model, LLM
API key, artist list, or fixed theme. The CLI remains available for login, diagnostics, scripting,
audits, and advanced sequencing.
understand → curate → ground → shape the arc → dry-run → createThe brief stays semantic. The host LLM reasons directly about imagery, mood, lyrical angle, era, cultural context, contrast, and the role of each song. It is not reduced to a handful of user-supplied sliders or an opaque theme-fit number.
Selection and sequencing stay separate. The model decides what belongs; measured BPM, key, energy, valence, and loudness can then diagnose transitions or refine order inside narrative blocks without overriding the musical idea.
Every candidate is grounded. Catalog resolution catches missing tracks, duplicates, wrong artists, and suspicious live/remastered versions before the dry run and final create step.
Listening evidence remains evidence. Replay history, recent plays, dates, and play counts can inform curation without silently becoming an algorithmic definition of the user's taste.
Local and private by design. The server runs on your machine; credentials stay in the local app config, and there is no bundled model, telemetry service, or extra LLM API key.
Portable MCP stdio. Works with Codex, Claude, Cursor, VS Code/Copilot, Gemini CLI, Windsurf, Cordis/DSH, Harness, and other clients that can launch a local stdio server.
Related MCP server: Sound
Recommended — install the MCP stdio service:
pip install apple-music-playlists
am-playlist status
am-playlist login # one-time Apple ID sign-inAlready use uv? Run the published package without a permanent install:
uvx --from apple-music-playlists am-playlist status
uvx --from apple-music-playlists am-playlist login
uvx --from apple-music-playlists am-mcpFor an MCP client, the equivalent Registry-aligned configuration is:
{ "mcpServers": { "applemusic": { "command": "uvx",
"args": ["--from", "apple-music-playlists", "am-mcp"],
"env": { "PYTHONIOENCODING": "utf-8" } } } }Register am-mcp in the client. The common configuration shape is:
{ "mcpServers": { "applemusic": { "command": "am-mcp",
"env": { "PYTHONIOENCODING": "utf-8" } } } }Then describe the result, not the implementation:
Create a 25-track late-night driving playlist: atmospheric alternative R&B and electronic, mostly from the last ten years, no live versions, with a calm landing.
Clients with MCP Prompt support can select create_playlist_from_description. In every other
client, send the same request in chat: the server instructions and typed tools expose the same
status → candidate pool → catalog grounding → direct comparison → dry-run → create workflow.
From a clone (nothing to install):
git clone https://github.com/Z-Han-Z/apple-music-playlists.git
cd apple-music-playlists
python am_playlist.py status # auto-fetches the developer token
python am_playlist.py login # one-time Apple ID sign-in (~6 months validity)
python am_mcp_server.py # register this absolute script path in the MCP clientInstallation also puts the CLI and MCP commands on your PATH:
am-playlist status # the CLI
am-playlist login # one-time Apple ID sign-in
am-mcp # the MCP stdio serverFor development, pip install -e . from a clone makes edits take effect without reinstalling.
See SETUP.en.md for the credential walkthrough (three ways to get the user token, including a zero-dependency one).
This is deliberately harder than “make me a workout playlist.” The brief asks music to carry a plot, and some of its constraints cannot be expressed as tempo or mood sliders:
Build a 12-track, three-act story in which a machine wakes in a city, mistakes attention for intimacy, asks to be touched, becomes vulnerable, and sees dawn. Cross electronic music and art pop from the late 1970s to the present; use one track per artist, studio recordings only, and let the voices become progressively more human. The ending must feel quiet and earned, not merely low-energy.
The run below used the public US Apple Music catalog on 2026-09-23. It did not read or write a private library.
22 LLM-proposed candidates
└─ 22 catalog matches returned exact title, artist, album, date, ISRC, and version metadata
├─ rejected: “Open Eye Signal (Mixed)” — resolved to a 2025 DJ Mix, not the studio cut
├─ rejected: “Deeper Understanding (2018 Remaster)” — not the requested original recording
└─ 12 final selections
Final create dry-run: 12/12 matched; no write performed
Audio-feature coverage: 12/12 usable (100%)
Flow cost, narrative locks: 44.14 → 41.14Each title below opens the exact US catalog recording returned by the resolver, so the sequence can be auditioned rather than taken on trust.
Act | Grounded order | What the sequence is doing |
I — Boot | The Robots — KraftwerkTechnopolis — Yellow Magic OrchestraKid A — Radiohead | A body, then a city, then an unstable first-person voice. |
II — Desire | Oblivion — GrimesDigital Witness — St. VincentIs It Cold In The Water? — SOPHIETouch — Daft Punk & Paul WilliamsAll Is Full of Love — Björk | Public attention becomes bodily risk, transformation, a request for contact, and finally an answer. |
III — Re-entry | Cellophane — FKA twigsRetrograde — James BlakeLong Road Home — Oneohtrix Point NeverAn Ending (Ascent) — Brian Eno | The synthetic shell fails; retreat becomes return, and the story lands at dawn. |
The interesting failure happened during ordering. With only the three acts locked, the numerical
optimizer cut the measured cost from 48.28 to 14.88 — but put Retrograde after the dawn and
made All Is Full of Love answer a request that had not happened yet. That is cheaper and worse.
The host model therefore added semantic beat boundaries (request → answer, return → dawn) and
let am_optimize_order make only local changes inside those boundaries. Selection and story stayed
linguistic; BPM, key, energy, and valence remained supporting evidence.
[
"The Robots - Kraftwerk",
"Technopolis - Yellow Magic Orchestra",
"Kid A - Radiohead",
"Oblivion - Grimes",
"Digital Witness - St. Vincent",
"Is It Cold In The Water? - SOPHIE",
"Touch - Daft Punk",
"All Is Full of Love - Björk",
"Cellophane - FKA twigs",
"Retrograde - James Blake",
"Long Road Home - Oneohtrix Point Never",
"An Ending (Ascent) - Brian Eno"
]This is the normal MCP workflow: the host model interprets the brief and proposes more candidates
than it needs; am_resolve_candidates grounds them; the model chooses and assigns narrative roles;
am_optimize_order optionally checks local flow without crossing semantic boundaries; and
am_create_playlist(dry_run=true) verifies the exact final recordings before the write.
File | Purpose |
| Core: token management, catalog search, create / edit / delete playlists, track resolution |
| Primary MCP stdio service: one description-to-playlist prompt plus 13 tools |
| Metadata audit: length, artist concentration, genres, eras, durations, duplicates, interludes |
| Audio-feature audit: BPM / key / loudness / energy / valence, adjacency checks, arc shape |
| Simulated-annealing track ordering against the measured rules |
| Listening history: recently played, and per-track/album/artist play counts (Apple Music Replay backend) |
| Descriptive sample profile: measured BPM / energy / valence spread and sample-relative quadrants; it does not define the user's taste |
| Your library: paged export of every catalog-backed song you own, enriched with ISRC / year / genre |
| Listening-evidence pool: merge recent plays with multiple Replay years, retaining dates and play counts for the LLM to interpret |
Supporting modules:
File | Purpose |
| Platform-neutral core: Camelot, BPM folding, the four adjacency rules, the six narrative shapes. Imports nothing from this project and nothing third-party |
| Platform-neutral paths and version — where config and cache live |
| The single |
All three analysis modules are importable as libraries:
import playlist_flow, playlist_audit, playlist_optimize
print(playlist_flow.flow_report("My Playlist")) # -> str
print(playlist_audit.audit_report("My Playlist")) # -> str
ids, report = playlist_optimize.optimize("stack.json") # -> (list[str], str)The standard prompt create_playlist_from_description asks for a natural-language brief and
optional name, track count, and response language. Curation stays in the host model; the tools are
the grounded Apple Music execution layer:
am_status · am_search_songs · am_resolve_candidates · am_list_playlists · am_show_playlist ·
am_create_playlist · am_add_tracks · am_delete_playlist ·
am_audit_playlist · am_analyze_flow · am_optimize_order ·
am_recently_played · am_top_played
am_resolve_candidates grounds a generous LLM-proposed pool in real catalog metadata, flags
duplicates and suspicious versions, and deliberately does not score theme fit. The host model
compares candidates directly with the user's words and explains their playlist roles.
am_analyze_flow diagnoses transitions; am_optimize_order can optionally refine ordering inside
already chosen narrative blocks. It never decides which songs belong in the playlist.
Mount it in a Cordis agent preset with the template in preset/, or wire it into
any other MCP client with:
{ "mcpServers": { "applemusic": {
"command": "python", "args": ["/abs/path/am_mcp_server.py"] } } }Complete tested examples for Codex, Claude, Cursor, VS Code/Copilot, Gemini CLI, Windsurf, Docker, Cordis/DSH, and Harness are in docs/client-setup.md.
Build the non-root local container with:
docker build -t apple-music-playlists:1.4.0 .The client must run it attached with docker run --rm -i; mount only the app config directory and
a writable cache as shown in the client guide. Config stays writable so token refresh can persist.
Never bake Apple credentials into the image.
python -m unittest discover -s tests -vThe suite is entirely offline — no network, no credentials. Two kinds:
Behaviour: the pure math that decides what "sounds good" — Camelot mapping, BPM folding, arc classification, each adjacency penalty asserted in isolation, annealing determinism and the block-order constraint. All six narrative archetypes must classify as themselves.
Structural regressions, each pinned to a bug that actually shipped: no hardcoded catalog
region, exactly one catalog_meta, no non-None --storefront default, cache outside the
repo, every MCP tool wired to a handler, and the optimizer free of platform imports.
They earn their keep immediately — the suite caught a syntax error in a file written minutes earlier, before it was ever run.
Apple's catalog API exposes no audio features at all — no tempo, key, loudness, energy, or
valence. Spotify's audio-features endpoint was shut off for new apps on 2024-11-27, and
AcousticBrainz retired in 2022.
playlist_flow.py bridges the gap with a free, key-less chain built on ISRC, which Apple does
return:
Apple Music track ──► ISRC
│
├─► api.reccobeats.com/v1/track?ids=<ISRC> → track UUID
│ └─► /v1/audio-features?ids=<UUID>
│ → tempo, key, mode, loudness, energy, valence,
│ danceability, acousticness, instrumentalness,
│ liveness, speechiness
└─ (fallback) musicbrainz.org ISRC lookupResults are cached locally, so the network cost is paid once per playlist.
Coverage is reported, never silently dropped. Every consumer prints a funnel saying why each track could not be measured:
Audio-feature coverage: 1,395/1,581 usable (88%)
· 80 tracks have no ISRC — the feature chain cannot start, so changing sources will not help
· 106 tracks are not in the current source — switch sources or analyse the audio locallyThat distinction is the point. No ISRC means the chain cannot start at all — a different feature source will not help. Not in the source means the ISRC is fine and switching sources (or analysing the audio locally) would fix it. Collapsing both into "missing features" discards the only information that tells you what to do next.
It matters more than it looks: tempo / key / energy / valence are the only things the
adjacency rules and the arc can act on, so coverage is the ceiling on how good an ordering can
be. At 60% coverage, four positions in ten were never evaluated — while the cost number still
looks excellent. The optimizer therefore prints coverage above its cost lines, and warns below 90%.
Derived from the research collected in docs/ — including a PLOS ONE study in which
130 music professionals sequenced albums, and a randomized trial on mood-adaptive music ordering.
Hard adjacency rules
No two slow tracks adjacent
Avoid "only slightly slower" transitions (0–12% drop makes the slower track feel like it drags)
Adjacent tracks must not be similar in both tempo and key
No unjustified large BPM jumps (>40%); no jarring energy shifts under incompatible keys
These four have exactly one definition, in playlist_core.check_pair(), and both the audit and
the optimizer call it. They used to be implemented twice, and the copies disagreed: the audit
called a track "slow" below the tempo's 25th percentile while the optimizer used a fixed 100 BPM,
and the audit never checked the BPM-jump rule at all. That is a tool diagnosing against one
standard and repairing against another — so the count it reported could not be trusted.
Note on the "slow" threshold. It is absolute (100 BPM), not data-driven, deliberately: the optimizer evaluates the same sequence thousands of times while annealing, and a percentile threshold would drift as the permutation changes, so the cost would never settle. The cost is that a uniformly slow playlist flags every adjacent pair — that is real, not a sequencing failure, and the report says so.
Global arc — you choose the target shape:
python playlist_optimize.py stack.json --arc cinderella
python playlist_optimize.py --list-shapesAxis | Target |
| the chosen narrative archetype |
| inverted U — fast in the middle |
Six shapes: rags-to-riches, tragedy, man-in-a-hole (default), icarus, cinderella,
oedipus. The target curve and the shape the audit classifies come from the same table in
playlist_core.ARCHETYPES, so "what shape is this" and "what shape am I aiming for" cannot drift
apart.
Tempo deliberately does not follow the chosen shape. The archetypes describe an emotional trajectory (valence / arousal); "put the fast ones in the middle" is a sequencing convention. Making tempo follow Cinderella too would conflate two independent principles.
Measuring this on a real arc playlist is what justified wiring it up: under man-in-a-hole — the
shape the optimizer used to hardcode — that playlist's opening 30 tracks score an arc cost of
2.95, the worst of the six. The same tracks score 1.19 under cinderella. The tool had
been aiming at the one shape that fit least.
The optimizer preserves your grouping (movements / eras / moods) and only reorders within groups, so thematic structure survives the loudness tuning. Drop the grouping and it reorders freely — measurably "smoother", at the cost of your narrative.
Example from a real run: cost 104.46 → 19.41 with grouping preserved, → 1.28 ungrouped.
Responses can be gzip-compressed even when you never sent Accept-Encoding. Decoding the
raw bytes as UTF-8 yields garbage that looks like an empty body. (This is fixed in am_playlist.py.)
DELETE only works on amp-api.music.apple.com. The documented host api.music.apple.com
returns 401 for playlist and library-song deletion.
Do not send x-apple-client-version to amp-api — it turns into a 500.
Creating a playlist also adds its tracks to the library. Deleting the playlist does not remove them.
BPM estimates have octave ambiguity (90 vs 180 for the same track). Fold into [70,160)
before comparing, or "two slow tracks adjacent" over-reports by ~4×.
Never pass "Title - Artist" straight into catalog search — you get live/remastered takes.
Search on the space-separated form and score versions afterwards.
An artist missing from a storefront's search ≠ the song is unavailable there. Look it up by ISRC.
Only the client that created a playlist can modify it — Apple-side restriction.
More in docs/apple-music-api-notes.md and
skill/reference.md.
Doc | Contents |
Credentials: what tokens exist, how to get each one, security notes, troubleshooting | |
Client-specific MCP, Docker, Cordis/DSH, generic harness, and Harness Platform setup | |
Maintainer-only PyPI and official MCP Registry publishing checklist | |
Token model, endpoint contracts, measured API behaviour, eval of 7 automation approaches | |
Curation methodology: adjacency physics, arc data, six narrative shapes, the ISO principle | |
Survey of published curation guidance (platform rules, DJ methods, academic findings) | |
LLM-native curation: direct candidate comparison, catalog grounding, readable constraints, and why scalar theme scores stay out of the critical path | |
Five difficult multilingual briefs with auditable constraints and blind-listening questions—no golden track lists | |
Review boundary for early heuristics: which decisions belong to the LLM and which deterministic algorithms should retain | |
The platform-adapter boundary: what is platform-neutral, what an adapter must provide, and what breaks on a service that exposes no ISRC | |
Concise agent-readable map of the curation boundary and the most useful project documents | |
Agent skill: workflow + the accumulated gotcha list | |
Release history, including behaviour changes between versions | |
Cordis agent preset template that mounts the MCP server |
For the complete Simplified Chinese guide, see README_ZH_CN.md.
Contributing — development workflow, architecture boundaries, and review expectations
Support — where to ask questions, report bugs, or propose features
Code of Conduct — participation standards and private reporting route
Security policy — supported versions and confidential vulnerability reporting
MIT — see LICENSE.
Unofficial community tooling. Not affiliated with or endorsed by Apple. Uses your own Apple Music account for personal use; follow Apple's terms of service.
Append resolved tracks to an existing playlist created by this API client. Use dry_run=true to preview matching; use am_create_playlist for a new playlist. / 中文：向已有歌单追加曲目。注意 Apple 的限制：只有创建该歌单的那个客户端才能写入它。
| Name | Required | Description | Default |
|---|---|---|---|
| isrcs | No | ||
| tracks | Yes | '歌名 - 艺人' 列表 | |
| dry_run | No | ||
| playlist | Yes | 歌单名或 p.xxxx ID | |
| storefront | No | 地区代码。不给则用配置里记住的账号地区，再兜底 us |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-idempotent write, but the description adds meaningful behavior beyond that: it is an append operation, dry_run previews matching, and Apple enforces client-ownership for writes. This gives the agent important operational context not available from the structured fields alone.
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 short, front-loaded with the core operation, and every sentence earns its place: the append action, the dry-run guidance, the create-playlist alternative, and the Apple ownership limitation. There is no filler or redundant restating of the title.
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 selection and invocation details are covered: target playlist scope, preview behavior, and the alternative for creating a playlist. However, there is no output schema, and the description does not explain return values, the role of isrcs, or the prerequisite relationship with am_resolve_candidates. These gaps are not fatal, but they leave some call decisions 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?
The schema documents tracks, playlist, and storefront, while the description adds useful meaning for dry_run. However, the isrcs parameter is completely unexplained, and the phrase 'resolved tracks' is not reconciled with the schema's 'song name - artist' format. With 60% schema coverage, the description helps but leaves a noticeable 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 opens with a specific verb ('Append') plus a clear resource ('existing playlist created by this API client'). It also distinguishes itself from am_create_playlist, which is the main ambiguity among siblings. An agent can quickly tell what this tool does and which sibling it is not.
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 explicitly tells the agent when dry_run=true should be used ('preview matching') and names the alternative for creating a new playlist ('use am_create_playlist for a new playlist'). The Apple ownership restriction also clarifies when this tool should not be used: playlists not created by this API client cannot be modified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only diagnosis of BPM, key, loudness, energy, mood, adjacent transitions, and overall arc. It may fetch and cache remote feature data; use am_optimize_order only when a proposed replacement order is wanted. / 中文：歌单「好听度」体检（音频特征层）：抓取每首的 BPM/调性/响度/能量/情绪值（经 ISRC→ReccoBeats，首次会慢，之后走缓存），然后检查四项相邻衔接（两首慢歌相邻 / 「只慢一点」/ tempo 与 key 同时相似 / 能量骤变）和整体弧线形状（Man in a hole、Icarus、Tragedy 等）。只读但会联网抓数据，可能耗时较久。
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | 忽略特征缓存重新抓取，默认 false | |
| playlist | Yes | 歌单名或 p.xxxx ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description explicitly discloses that the tool may fetch and cache remote feature data, that the first call is slow due to ISRC→ReccoBeats lookup, and that later calls use cache. This adds real behavioral context about side effects, latency, and network usage that annotations alone do not provide.
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 English portion is tightly front-loaded and scoped, and the Chinese section adds valuable specifics about transition checks and arc shapes. The bilingual duplication makes it longer than strictly necessary, but each half still carries useful detail.
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 moderately complex analysis tool with no output schema, the description covers what is analyzed, the data source, caching behavior, latency, and the key sibling distinction. It does not explicitly describe the return shape, but the named diagnostic dimensions give a strong inference of what the result will contain.
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 playlist and refresh. The description's cache discussion aligns with the refresh parameter but does not add new parameter-level semantics beyond what the schema states; therefore the 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 opens with a specific verb-resource pair ('Read-only diagnosis of BPM, key, loudness, energy, mood, adjacent transitions, and overall arc') and names the exact analysis scope. It also explicitly distinguishes itself from am_optimize_order, so an agent can tell this is an analysis tool, not a reordering tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly says to use am_optimize_order only when a proposed replacement order is wanted, which routes the agent away from the closest sibling. It also conveys the read-only nature and the potentially long runtime, but it does not enumerate exclusions for other siblings such as am_audit_playlist or am_show_playlist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only metadata audit of playlist length, artist concentration, genres, eras, duplicates, and possible interludes. For BPM, key, energy, and transitions, use am_analyze_flow. / 中文：歌单结构化体检（元数据层）：曲目数、总时长、艺人集中度（同一艺人是否超过 2 首）、流派分布、年代分布、时长分布、重复曲目、<2:00 的疑似间奏。只读，用于判断歌单是否符合策展规范（长度 20–30 首最佳、单一主题等）。
| Name | Required | Description | Default |
|---|---|---|---|
| playlist | Yes | 歌单名或 p.xxxx ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact audit scope and curation norms (e.g., 20–30 tracks best, same-artist threshold, suspected interludes under 2:00). It reinforces the read-only nature without contradicting 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 English portion is front-loaded and concise, with the alternative routing in the second sentence. The Chinese section repeats some content but also adds unique details such as duration distribution, the same-artist threshold, and the 20–30 track curation guideline, so it is not pure 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?
For a single-parameter, read-only audit tool with strong annotations, the description is nearly complete: it tells the agent what is audited, what standards are applied, and when to use a different tool. The lack of an output schema means the return format is unspecified, but the listed audit dimensions give enough context for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'playlist' parameter is already described as '歌单名或 p.xxxx ID'. The tool description adds no additional parameter-level semantics, so the baseline of 3 applies because the schema carries the full burden.
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 names a specific verb ('audit') and resource ('playlist metadata') and enumerates concrete audit dimensions: length, artist concentration, genres, eras, duplicates, and possible interludes. It also explicitly distinguishes the tool from the sibling am_analyze_flow by routing BPM, key, energy, and transitions elsewhere, so an agent can disambiguate without opening schemas.
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 states when to use this tool: for metadata-layer playlist audits and curation-rule checks. It also names the alternative: 'For BPM, key, energy, and transitions, use am_analyze_flow.' This is explicit routing guidance with a condition, matching the high standard of the calibration example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new playlist from 'Title - Artist' strings or ISRCs. Use dry_run=true to verify catalog matching without writing; use am_add_tracks for an existing playlist. / 中文：创建一个新的 Apple Music 歌单，并一次性写入曲目。曲目用 '歌名 - 艺人' 形式的字符串数组给出，服务端会自动在 catalog 里匹配；若有 ISRC 码则更精确。这是全自动建歌单的主入口。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | 歌单名称 | |
| isrcs | No | tracks 是否按 ISRC 精确匹配（更快、更准） | |
| tracks | Yes | 曲目列表，每项形如 '歌名 - 艺人'；或用 --isrcs 时填 ISRC | |
| dry_run | No | 只解析曲目不写入，用于预览匹配结果 | |
| storefront | No | 地区代码。不给则用配置里记住的账号地区，再兜底 us | |
| description | No | 歌单描述，可选 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-readonly, non-idempotent write operation, so the description doesn't contradict them. It adds meaningful behavior: server-side catalog matching, all-at-once track writing, ISRC precision, and dry-run semantics that bypass actual writes.
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 English description is front-loaded and compact: primary behavior, key mode, and alternative tool all in two sentences. The Chinese repetition adds length but serves a bilingual audience and doesn't introduce fluff.
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 6-parameter creation tool with no output schema, the description covers the essential call path: what to provide, how matching works, dry-run mode, and which sibling handles existing playlists. It doesn't describe the response shape or error cases, but that is not critical for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how 'tracks' are matched server-side, that ISRCs are more precise/faster, and that dry_run prevents writing – clarifying relationships between parameters that the raw schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('new playlist') plus the input form ('Title - Artist' strings or ISRCs), and explicitly distinguishes itself from am_add_tracks. The Chinese portion reinforces '全自动建歌单的主入口', making its role unmistakable.
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 explicitly instructs when to use dry_run=true for verification without writing, and directs users to am_add_tracks for existing playlists. This gives clear selection criteria among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one playlist permanently after it has been shown to the user. This is destructive, requires confirm=true, and does not delete the underlying songs from the library. / 中文：删除一个歌单。这是破坏性操作，必须先把歌单名和它当前的内容展示给用户并得到确认；只删本工具创建的演示/临时歌单，不要删用户自己整理的歌单。
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | 必须显式传 true 才会真正删除 | |
| playlist | Yes | 歌单名或 p.xxxx ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnly=false, and the description goes beyond them by adding permanence, the confirmation requirement, the prerequisite of prior display, and the key side effect that songs are not deleted. This materially improves safe invocation.
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 compact English sentences front-load the action and risk, followed by a concise Chinese restatement. Every sentence carries safety, scope, or side-effect information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers prerequisites, side effects, parameter constraints, and prohibited use cases. An agent has enough information to call it correctly and avoid data loss.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by constraining playlist values to tool-created demo/temporary playlists and emphasizing that confirm must be explicitly true. This is a meaningful extension beyond the schema, though not exhaustive.
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 opens with a specific verb and object ('Delete one playlist permanently') and immediately clarifies scope: it does not delete underlying songs and only targets tool-created demo/temporary playlists. This clearly differentiates it from inspection, creation, and audit 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?
It states exactly when the tool may be used—only after the playlist has been shown to the user and explicitly confirmed—and when it must not be used, namely on user-curated playlists. The confirm=true requirement acts as an actionable gate for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every playlist in the current user's library, including IDs. Use am_show_playlist when the tracks of one playlist are needed. / 中文：列出当前账号音乐库里的所有歌单（含 ID）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds scope (current user's library) and output content (IDs), but does not add further behavioral context such as pagination or rate limits. With annotations carrying the main burden, this is adequate.
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 compact and front-loaded with the key action and scope. The second sentence routes to a relevant sibling, and the Chinese translation serves multilingual users without adding conceptual clutter.
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 zero-parameter, read-only list operation, the description fully covers purpose, scope, output (IDs), and sibling routing. No output schema is present, but the description gives enough detail about what the agent can expect.
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 takes zero parameters, and the schema has 100% coverage with no properties. The description does not need to explain parameters, so the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: list every playlist in the current user's library, including IDs. It also differentiates itself from the sibling am_show_playlist, which focuses on tracks of a single playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names the alternative tool am_show_playlist and gives the condition for using it (when tracks of one playlist are needed). This gives the agent clear routing guidance beyond mere purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute a proposed order after the LLM has selected the songs and narrative blocks. It balances adjacent audio transitions with a chosen qualitative arc, returns an order without writing, and may fetch cached remote features; it must not choose songs or judge theme fit. / 中文：为一批曲目算出更好的顺序。这是本项目唯一会排序的工具——am_analyze_flow 只诊断（告诉你哪里有 2 处慢歌相邻、形状是 Icarus），不提供修法。这里用模拟退火在四条相邻硬规则（不要两首慢歌相邻 / 不要「只慢一点」/ 相邻不该在 tempo 与 key 上同时相似 / 不要 BPM 无理由大跳、能量骤变）与选定叙事弧之间取平衡。只读：只返回建议顺序，不动任何歌单；把返回列表按原顺序交给 am_create_playlist 即可。因为需要每首的 BPM/调性，首次会联网抓特征（之后走缓存）。
| Name | Required | Description | Default |
|---|---|---|---|
| arc | No | 目标叙事弧，默认 man-in-a-hole（先落再起）。用 cinderella 表示起-落-起，等等 | |
| isrcs | No | tracks/blocks 是否按 ISRC 精确匹配，默认 false | |
| blocks | No | 分组排序：每个子数组是一个乐章/段落，**段落之间的先后顺序保持不动**，只在段落内部重排。想保留叙事结构时用它（与 tracks 二选一） | |
| tracks | No | 要排序的曲目，每项 '歌名 - 艺人'（配 isrcs=true 时填 ISRC） | |
| refresh | No | 忽略音频特征缓存重抓，默认 false | |
| playlist | No | 要重排的现有歌单名或 p.xxxx ID（与 tracks/blocks 二选一） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'returns an order without writing' and is 'read-only', consistent with readOnlyHint and destructiveHint, but adds meaningful behavior not visible in annotations: it may fetch remote audio features on first use and cache them afterward, and it uses simulated annealing with four hard rules balanced against a narrative arc. This gives the agent a realistic model of side effects and computation.
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 English opening is compact and the Chinese expansion adds dense, non-redundant detail about sibling differentiation, hard constraints, cache behavior, and the downstream workflow. It is long, but every sentence earns its place; the main cost is bilingual duplication of the core concept.
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 tool with six optional parameters and no output schema, the description covers the full lifecycle: when to invoke it, what it must not do, what algorithm it uses, what side effects it has, how the output should be consumed, and how it relates to a sibling tool. Little is left for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that tracks/blocks are LLM-selected inputs rather than something the tool picks, that arc is a qualitative tradeoff against hard ordering rules, and that feature fetching/caching underlies the refresh and network behavior. It does not enumerate every parameter, but the schema already handles that.
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 opens with a specific verb and resource: 'Compute a proposed order' for songs and narrative blocks. It further distinguishes this tool from siblings by stating it is 'the only tool that sorts' and explicitly says it 'must not choose songs or judge theme fit', eliminating ambiguity about its exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent exactly when to use the tool: 'after the LLM has selected the songs and narrative blocks'. It also names the alternative, am_analyze_flow, as diagnostic-only and says it doesn't provide fixes, so the agent knows to come here for reordering rather than diagnosis. The workflow note about passing the returned list to am_create_playlist further anchors usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent listening or recently added Apple Music content when recency matters. This API does not provide play counts; use am_top_played for Replay rankings. / 中文：查最近播放。kind=tracks 是最近播放的曲目；played 是最近播放的歌单/专辑；stations 是最近听的电台；added 是最近加入音乐库的内容。注意：Apple 的这个接口不返回播放次数。
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | 默认 tracks | |
| limit | No | 条数，默认 30 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a non-obvious limitation—this endpoint does not return play counts—and frames the response as recency-based, which is useful beyond the structured annotations. It does not go into response shape or pagination, but that is not a critical gap for a read-only list endpoint.
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 English and Chinese sections cover similar ground, including repeating the 'no play counts' caveat, which adds redundancy. The description is still relatively compact and front-loads the main purpose and limitation, but some sentences duplicate content.
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 two-parameter list tool with complete schema coverage and strong annotations, the description covers the key context: when to use it, what each kind returns, and a critical limitation. It does not describe the output schema, but none exists, and the simple list-like nature of the tool makes the description sufficient for correct 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining what each kind value represents semantically (e.g., played means recently played playlists/albums, stations means recently listened radio). The limit parameter is already fully specified by the schema's min/max/default, so no additional explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads recent listening or recently added Apple Music content, with a specific verb and resource. It also distinguishes itself from am_top_played by noting this API does not provide play counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool 'when recency matters' and directs users to am_top_played for Replay rankings when play counts are needed. The Chinese section further clarifies the intended use for each kind value, giving the agent concrete selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ground an LLM-curated candidate pool in Apple Music metadata before final selection or creation. It returns exact catalog metadata and Apple Music links, flags unresolved tracks, duplicate recordings, artist concentration, and version markers, and never scores theme fit or writes to the library. / 中文：批量校验 LLM 提出的候选曲目，并返回 Apple Music 的真实曲名、艺人、专辑、发行日期、流派、时长、歌词可用性、版本标记和 catalog ID。还会指出重复录音与艺人集中度，但不替模型做主题评分或选曲。模型应直接根据用户描述与这些真实信息比较候选，保留理由充分的曲目。只读，不修改音乐库。
| Name | Required | Description | Default |
|---|---|---|---|
| tracks | Yes | 候选曲目，每项形如 '歌名 - 艺人'。建议先给目标数量的 1.5–2 倍。 | |
| storefront | No | 可选地区代码；默认使用账号地区 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond these: it returns exact catalog metadata and links, flags unresolved tracks, duplicate recordings, artist concentration, and version markers, and explicitly states it never scores theme fit or writes to the library. This provides a rich behavioral profile without contradicting 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 English portion is two sentences, front-loaded with the primary purpose, followed by a list of outputs and non-actions. The Chinese translation adds specific metadata fields (release date, genre, duration, lyrics availability) that enrich the description, but the overall structure is efficient and no sentence is wasted. The purpose is stated first, and the key constraints (no scoring, no writes) are included.
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 there is no output schema, the description compensates by specifying what is returned (exact catalog metadata and links) and what issues are flagged (unresolved tracks, duplicates, artist concentration, version markers). It does not detail the exact output structure or error handling, but for a resolution tool this is acceptable. It also covers usage context (before selection) and safety (read-only). The description is sufficient for an agent to call 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%: both parameters (tracks and storefront) have descriptions in the schema, including format for tracks and default for storefront. The tool description does not add extra parameter semantics beyond what the schema already provides, so it meets the baseline but doesn't exceed it.
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: to ground an LLM-curated candidate pool in Apple Music metadata before final selection or creation. It specifies the verb (resolve/ground), the resource (candidate pool vs. Apple Music metadata), and explicitly distinguishes from other operations by stating it never scores theme fit or writes to the library. This differentiates it from sibling tools like am_search_songs (search) and am_create_playlist (creation).
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 timing guidance: use 'before final selection or creation'. It also states what the tool does not do (scoring, writing), implying it should not be used for those purposes. However, it does not explicitly name alternative tools (e.g., 'use am_search_songs to find songs'), leaving some inference to the agent. The context is clear enough, but explicit exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Apple Music catalog for a small exploratory lookup and return stable catalog IDs. For an LLM-proposed playlist-sized pool, use am_resolve_candidates instead. / 中文：在 Apple Music catalog 搜索歌曲/专辑/艺人，返回可用于建歌单的歌曲 ID。
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | 搜索词，例如 '晴天 周杰伦' 或 'Bohemian Rhapsody' | |
| limit | No | 返回条数，默认 5 | |
| types | No | songs / albums / artists，默认 songs | |
| storefront | No | 地区代码（如 us / jp / cn）。不给则用配置里记住的账号地区，再兜底 us |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations: results are stable catalog IDs suited for later playlist construction, and the search is intentionally lightweight. This is meaningful behavioral information for downstream use.
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 core guidance is front-loaded in one tight sentence, followed by an explicit alternative and a short Chinese translation. The translation is redundant for an English-speaking agent but not bloated; the structure is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with fully documented parameters and no output schema, the description is nearly complete: it states the purpose, the return value type (stable IDs), and the appropriate scale. The only minor gap is no explicit mention of default types or storefront fallback, but the schema covers those details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is documented in the schema. The description adds some meaning by referencing songs/albums/artists (matching the types parameter) and IDs, but it does not add details about limit or storefront that the schema lacks. A 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 states a specific action (Search), a clear resource (Apple Music catalog), and a precise purpose: small exploratory lookups returning stable catalog IDs. It explicitly distinguishes itself from am_resolve_candidates, so an agent can tell them apart immediately.
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?
Directly instructs when NOT to use this tool: for LLM-proposed playlist-sized pools, use am_resolve_candidates instead. It also frames the intended scope as 'small exploratory lookup,' giving clear selection criteria without needing to inspect sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the tracks in one playlist selected by name or ID. Use am_list_playlists first when the exact playlist is unknown. / 中文：查看某个歌单的曲目列表。
| Name | Required | Description | Default |
|---|---|---|---|
| playlist | Yes | 歌单名或 p.xxxx 形式的 ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the selection-by-name-or-ID behavior, which is useful, but does not disclose return format or pagination. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with a clear verb and resource, plus a helpful usage pointer. The Chinese translation is redundant but does not harm. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only single-parameter tool with full schema coverage and safety annotations, the description is nearly complete. It could mention the return format, but the output schema is absent and the tool is simple enough that an agent can infer the result from the title and description.
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 the single parameter. The description adds that the parameter can be a name or p.xxxx ID, which matches the schema's description. Baseline 3 is correct when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Show') and resource ('tracks in one playlist'), and distinguishes it from siblings by noting selection by name or ID. It clearly identifies what the tool does and is not a tautology.
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 explicitly advises using am_list_playlists first when the exact playlist is unknown, providing clear context for when to use this tool. It does not explicitly state when not to use it, but the guidance is sufficient for the simple use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check developer-token validity and Apple Music login status. Use before any library write; this check changes nothing. / 中文：查看 Apple Music 自动化状态：developer token 是否有效、是否已登录（music-user-token）。任何写歌单操作前都应先确认已登录。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds 'this check changes nothing,' reinforcing the safety profile, and clarifies the auth-related checks (developer-token, music-user-token) which are not fully spelled out in annotations. It provides additional behavioral context without contradicting anything.
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 English description is two sentences front-loading the core purpose and usage. The Chinese translation adds specific detail (music-user-token) and repeats the usage guidance, earning its place for the target audience. There is no filler or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status check with annotations already covering safety, the description is complete. It explains what is checked, when to use it, and that it has no side effects. No output schema or return-value description is necessary for an agent to call this 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?
The tool has zero parameters, so the schema is trivially complete (100% coverage). The baseline for 0 params is 4, and the description does not need to add parameter semantics. It correctly focuses on the action and purpose.
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 checks developer-token validity and Apple Music login status, using a specific verb ('Check') and resource. It is easily distinguished from siblings like am_search_songs or am_create_playlist, which have entirely 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 explicitly says 'Use before any library write' and reiterates in Chinese that any song list write operation should confirm login first. This gives clear when-to-use guidance and implies exclusion from non-write contexts, even though no alternative tool is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Apple Music Replay play-count rankings by song, album, or artist when frequency matters. Use am_recently_played for latest listening; all-time data may be unavailable, so retry with a specific year. / 中文：查播放次数排行（数据来自 Apple Music Replay / 音乐回忆的后端）。可以查 songs / albums / artists，按年份或 all-time。返回每项的播放次数、首次播放日期、最近播放日期。注意：只有 amp-api 主机可用；all-time 期间不一定存在，失败时先试具体年份。
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | 默认 songs | |
| year | No | 如 2026；不给则用 all-time | |
| limit | No | 条数，默认 30 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: the data source (Apple Music Replay backend), the output fields (play count, first/last played dates), the host constraint (only amp-api available), and the caveat that all-time data may not exist. This goes beyond annotations and helps the agent anticipate behavior.
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 English portion is concise and front-loaded with purpose and usage, followed by caveats. The Chinese translation duplicates the same content, adding length without new information, but it is not overly verbose and may serve multilingual contexts. Overall, the structure is efficient, though slightly redundant.
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 query tool with three parameters and no output schema, the description covers purpose, usage, output fields, host constraints, and data-availability caveats. It includes a fallback strategy for the all-time case. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it mentions kind and year in passing but does not elaborate on formats or edge cases. The description of return fields is useful but not parameter semantics. It meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads Apple Music Replay play-count rankings by song, album, or artist, with a specific verb and resource. It explicitly differentiates from am_recently_played, so an agent can distinguish it from siblings without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: use am_recently_played for latest listening, and this tool when frequency matters. It also advises retrying with a specific year if all-time data is unavailable, which is practical usage guidance beyond just a description.
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.0am_add_tracksam_analyze_flowam_audit_playlistam_create_playlistam_delete_playlistam_list_playlistsam_optimize_orderam_recently_playedam_resolve_candidatesam_search_songsam_show_playlistam_statusam_top_playedScored across 13 tools
Most tools have clearly distinct purposes, but a few pairs (am_search_songs vs am_resolve_candidates, am_audit_playlist vs am_analyze_flow) overlap enough that an agent must read descriptions carefully to pick correctly. Overall the separation is logical and well-documented.
All tools follow a consistent am_ prefix with snake_case verb_noun naming (search_songs, create_playlist, analyze_flow, etc.). This makes the toolset predictable and easy to navigate.
13 tools is well-scoped for an Apple Music automation server covering status, search, playlist CRUD, analysis, and listening history. Each tool earns its place without the set feeling bloated or thin.
The surface covers playlist creation, reading, adding tracks, deletion, and rich analysis/optimization workflows. Missing operations like renaming a playlist, removing tracks, or reordering an existing playlist in place are notable gaps, but core curation flows remain usable.
Create App Store screenshots, icons, ASO copy, localization, and revisions via hosted MCP.
iTunes Search MCP — Apple's public catalog search
Inspect and edit media canvases, run existing Flows, and retrieve results. Vyrl MCP token required.
Create, inspect, and manage Wubble music, speech, voice, and sound-effect requests through MCP.
