Public music-rights directory: who wrote and owns a song, its ISWC/ISRC/IPI, and licensing asks
Scored across 13 tools
There is real conceptual overlap: directory_search duplicates list_works+list_people, directory_lookup_isrc is an admitted alias for list_works with an isrc filter, and directory_chain overlaps the lookup tools. However, every one of these overlaps is called out explicitly in the descriptions ('equivalent to…', 'prefer over stitching…', 'NOT this tool'), which gives an agent a clear decision rule. Only a couple of boundaries (chain vs. lookup_work) still require judgment.
All tools share the directory_ prefix and snake_case, with a dominant verb_noun shape (list_people, lookup_work, search_recordings, send_licensing_enquiry). A few deviate: directory_chain and directory_release_notes are bare nouns, and directory_skill_get/skill_list invert the verb to the end. Minor but noticeable deviations from an otherwise strong pattern.
13 tools is well within a sane range for a catalogue directory, and each of the discovery, lookup, graph, audio, and licensing tools maps to a distinct workflow step. The meta tools (release_notes, skill_list, skill_get) are somewhat peripheral to the core domain but are cheap and non-conflicting.
The surface covers the full arc: browse (works/people), identifier lookup, chain/graph, audio-feature search, related-works suggestion, and the licensing outreach side effect, including an explicit safety protocol around sending. Minor gaps remain — no first-class publisher/label entity lookup, no way to view a user's prior enquiries or reply state, and no batch operations.
Use when the user asks: 'show me the rights chain for X', 'give me everything on this song', 'what's the full picture for X?', 'trace the chain from this writer to that work'. Graph lookup — resolves a query, ISWC, or ISRC to its full rights chain in one call. Each result bundles the work, its writers and publishers (names + roles, no IPIs or splits), the linked recording (ISRC, DSP presence, duration), and audio characteristics (BPM, key, energy). Prefer over stitching list_works + lookup_work + lookup_person when you want the whole graph around a track in a single round-trip. Supports audio-only queries (min_bpm, key, mood, etc.) when you don't have a text query. Work results carry programmable_since (every owner confirmed a locked split) and ready_to_license (composition and a master confirmed, with audio, ISRC and ISWC); filter to either with programmable_only / ready_to_license. → then: directory_lookup_work (deeper work detail), directory_list_people (research a named writer by name)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text query (work title, creator name, etc.). Minimum 2 characters. | |
| key | No | Musical key (e.g. 'C', 'F#', 'Bb') | |
| mood | No | Mood — one of: aggressive, ambient, calm, contemplative, dark, dramatic, dreamy, energetic, epic, ethereal, hopeful, intense, melancholic, nostalgic, passionate, playful, romantic, sad, tender, tense, triumphant, uplifting, warm. "happy" is read as "uplifting". Any other word is refused. A mood matches analysed recordings, and also listed songs whose owner set that mood on audio that is not analysed: those carry mood_note "mood set by the owner, not analysed" and no measured values. With a BPM, key, energy or other measured filter, only analysed recordings match. | |
| limit | No | Max results (default 10, max 20) | |
| max_bpm | No | Maximum BPM | |
| min_bpm | No | Minimum BPM | |
| key_mode | No | Key mode | |
| identifier | No | ISWC or ISRC — direct identifier lookup | |
| max_energy | No | Maximum energy, 0 to 1 (measured loudness) | |
| min_energy | No | Minimum energy, 0 to 1 — measured loudness, not a mood | |
| ready_to_license | No | Only works ready to license — composition and a master confirmed by every owner, that recording has audio and an ISRC, and the work has an ISWC. Audio results are the ready recordings themselves. Drops people from text results. | |
| programmable_only | No | Only programmable works — every owner confirmed a locked split, so a licence fee is paid to each without chasing sign-off. Drops people from text results. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent annotations, it discloses the one-call graph behavior, the contents of each bundled result, and the important exclusion that writers and publishers include names and roles but no IPIs or splits. It also explains the licensing-related result states, though it does not further detail query-resolution behavior or how empty or ambiguous matches are handled.
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 front-loaded with selection cues and then moves logically through behavior, alternatives, filters, and follow-up tools. It is dense and somewhat example-heavy, and the licensing definitions partly repeat the schema, but nearly every section serves a practical routing or invocation purpose.
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 complex 12-parameter lookup with no output schema, the description supplies the missing result-shape overview, explicit data limitations, licensing-state semantics, and downstream navigation. Together with the fully documented parameters and safety annotations, it provides enough context for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description adds useful cross-parameter guidance by explaining audio-only searches without a text query and connecting the work-level status fields to programmable_only and ready_to_license, but much of the individual filter semantics remains schema-driven.
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 gives a precise action and resource: a graph lookup that resolves a query, ISWC, or ISRC into a full rights chain. It further distinguishes the tool by its bundled work, contributor, recording, and audio data and by replacing a multi-tool lookup sequence.
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 opens with concrete request patterns, explicitly says to prefer it over stitching together list_works, lookup_work, and lookup_person for a whole-graph result, and identifies audio-only querying as another use case. The follow-up routing to directory_lookup_work and directory_list_people also clarifies where to go for narrower or deeper research.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'list creators in PICA', 'people starting with B', 'browse the people directory'. Browse and filter creators in the PICA public directory. Filter by free-text (q), ISNI, IPI, or starting letter (A–Z, or '#' for numeric). Returns paginated results. Each result carries global_creator_id, the ID directory_lookup_person takes. → then: directory_lookup_person (identifiers, roles, listed-work count and collaborators for one creator)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Text search across creator names | |
| ipi | No | Filter by IPI number | |
| isni | No | Filter by ISNI identifier | |
| page | No | Page number (default: 1, 20 results per page) | |
| letter | No | Filter by last name starting letter (A–Z), or '#' for numeric |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive/non-open-world behavior, so the safety profile is covered. The description adds what the annotations cannot: that results are paginated, that entries carry global_creator_id, and that this ID is the key the lookup tool consumes. It does not mention rate limits or total-count behavior, which keeps it short of a 5.
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 opening is front-loaded with the trigger condition, followed by capability, result shape, and next step in a logical order with no filler sentences. The quoted example queries are slightly redundant with the 'browse and filter' statement but they earn their place by anchoring to real user phrasing.
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 output schema, the description must carry return-value information, and it does identify the key returned field (global_creator_id) and the pagination model. It stops short of describing the other fields in a result row (name, ISNI/IPI presence), which an agent composing a response would benefit from, but nothing needed to invoke the tool correctly is missing.
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 already documented with its own description, and the description's filter list (q, ISNI, IPI, letter) mostly restates those fields. The one genuinely additive detail is spelling out that 'letter' accepts '#' for numeric entries, and that nuance also appears in the schema. Baseline 3 is correct here.
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 gives a specific verb and resource ('Browse and filter creators in the PICA public directory') and reinforces it with concrete user utterances such as 'people starting with B'. It also distinguishes itself from the sibling by naming directory_lookup_person as the drill-down step, so an agent can separate listing from lookup without reading either 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?
It states explicitly when to use the tool via quoted trigger phrases, and it names the concrete follow-on ('→ then: directory_lookup_person') for the case where the agent needs identifiers, roles, or collaborators. That is when-to-use, when-to-continue, and alternative routing all in one short block.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'list works in PICA', 'works starting with B', 'find works by publisher X', 'browse the catalog', 'a song about love', 'songs about X'. For a theme or subject, search its plain word in q ('love', 'home', 'summer'): titles carry the theme. Start here before any mood or sound search, which only narrows. Browse and filter musical works their owners have listed in the PICA public directory. Filter by free-text (q), ISWC, ISRC, publisher, label, or starting letter (A–Z, or '#' for numeric). Sort by title (default) or recent. Returns paginated results. Each work carries ai_origin: whether the OWNER declared it human-made, AI-assisted or AI-generated (or 'not stated' — never assume human-made), with ACRCloud's AI detection beside it. Set human_made_only to keep only works the owner declared human-made that ACRCloud does not call likely AI. → then: directory_lookup_work (full details with credits and audio)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Text search across work titles and identifiers | |
| isrc | No | Filter by ISRC (exact match, cross-table recording lookup) | |
| iswc | No | Filter by ISWC (e.g. T-123.456.789-0) | |
| page | No | Page number (default: 1, 20 results per page) | |
| sort | No | Sort order (default: title) | |
| label | No | Filter by record label (partial match) | |
| letter | No | Filter by title starting letter (A–Z), or '#' for numeric | |
| publisher | No | Filter by publisher name (partial match) | |
| human_made_only | No | Only works the owner declared human-made, leaving out any ACRCloud calls likely AI-generated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and idempotent annotations, it discloses the owner-listed public-directory scope, pagination, and the provenance and limitations of ai_origin. The warning never to assume 'not stated' means human-made, alongside the explanation of ACRCloud detection and human_made_only, is especially valuable behavioral context with no output schema present.
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 front-loaded with usage guidance and proceeds logically through scope, search behavior, result semantics, and the next tool. It is nevertheless a dense paragraph with six quoted examples and a filter list that partly duplicates the schema, so it is not maximally economical.
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 nine-parameter read tool without an output schema, it covers scope, selection criteria, search strategy, filtering, sorting, pagination, important result metadata, and the appropriate follow-up tool. Together with the fully documented schema and safety annotations, it supplies the context needed 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%, and much of the filter, letter, and sort wording repeats that structured documentation. However, the advice to use a plain theme word in q because titles carry the theme adds genuine search strategy, while the human_made_only explanation clarifies how owner declarations and ACRCloud detection interact.
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 identifies the action and resource: browsing and filtering musical works that owners have listed in the PICA public directory. It also distinguishes this tool from directory_lookup_work, which is explicitly reserved for full details, credits, and audio.
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 opens with concrete request patterns, explains how to handle theme or subject searches using q, and says to start here before mood or sound searches because those only narrow results. The explicit handoff to directory_lookup_work for full work details provides an additional clear selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'lookup ISRC X', 'what's the work for ISRC X?', 'find the work for this recording'. Shortcut: look up the work(s) associated with a recording identifier (ISRC). Equivalent to directory_list_works with an isrc filter, pinned for recording-first discovery. → then: directory_lookup_work (full details on the matched work)
| Name | Required | Description | Default |
|---|---|---|---|
| isrc | Yes | ISRC code (e.g. USABC1234567) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the equivalence to a filtered directory_list_works call and the 'work(s)' plural hinting that one ISRC can map to multiple works. It stops short of stating what happens on no match or how results are ordered, which would be the remaining behavioral gap.
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?
Front-loaded with the trigger condition, then the shortcut definition, then the chained next tool using an arrow marker — the structure mirrors how an agent reads it. The three quoted example utterances are mildly redundant with the verbatim purpose statement and the description is somewhat denser than needed, but nothing is 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 single-parameter, read-only lookup with no output schema, the description covers what it returns (the matched work(s)) and where to go for full details. Only the not-found / multiple-match outcome is unaddressed, a minor gap given the tool's simplicity.
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 schema documents the ISRC format with an example, so the baseline is 3. The description adds real meaning by framing ISRC as a recording identifier used for recording-first discovery, which disambiguates it from the work identifier expected by directory_lookup_work.
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 and resource (look up the work(s) for an ISRC) and explicitly distinguishes itself from siblings: equivalent to directory_list_works with an isrc filter, pinned for recording-first discovery. An agent can tell why this exists alongside directory_list_works and directory_lookup_work without opening any 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?
Gives concrete user phrasings that should trigger it ('lookup ISRC X', 'find the work for this recording'), states the alternative it wraps (directory_list_works with an isrc filter), and names the follow-up tool. When-to-use, the alternative, and the next step are all explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'lookup IPI 12345', 'lookup ISNI X', 'find creator by MusicBrainz ID'. Also use it for the profile of a creator already found with directory_list_people or directory_search. Looks up ONE creator in the PICA public directory by an identifier: global_creator_id (UUID, from directory_list_people or directory_search), ISNI, IPI number, or MusicBrainz ID. It does not accept a name: to find a creator by name, or to choose between several people with the same name, use directory_list_people (q) or directory_search first. Returns the creator's name, identifiers (IPI, ISNI, MusicBrainz), roles, the number of their works listed in the directory, their PICA profile grade, and up to five collaborators on those listed works. It does not list the works themselves: use directory_list_works or directory_search with the creator's name for those. An unknown identifier returns not found. → then: directory_list_works (their listed works, by name)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | global_creator_id (UUID) from directory_list_people or directory_search, an ISNI, an IPI number, or a MusicBrainz ID. Not a name, and not person_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it enumerates the returned fields (name, IPI/ISNI/MusicBrainz, roles, work count, profile grade, up to five collaborators), discloses the failure mode ('An unknown identifier returns not found'), and states the cardinality limit (one creator only). With no output schema, this return-value disclosure carries real weight.
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?
Front-loaded with trigger phrasings, then scope, then returns, then the next step – a sensible order with no filler sentences. Minor redundancy: the 'not a name' exclusion is stated twice (once in the opening routing sentence, once as 'It does not accept a name'), and the trailing '→ then: directory_list_works' partially repeats the earlier works-tool mention.
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 one-parameter lookup with no output schema, the description supplies everything an agent needs: accepted identifier forms, single-result cardinality, the returned field set, not-found behavior, and the correct follow-up tool for the adjacent task. Nothing material is left 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 coverage is 100% and the single 'id' parameter's description already lists global_creator_id, ISNI, IPI, and MusicBrainz ID plus the 'not a name, and not person_id' exclusion. The description restates this almost verbatim, adding only the provenance hint that the UUID comes from directory_list_people or directory_search, which the schema also mentions. Correct baseline of 3 for a fully documented single parameter.
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 and resource ('looks up ONE creator in the PICA public directory by an identifier') and explicitly enumerates the four accepted identifier types. It distinguishes itself from siblings by naming directory_list_people, directory_search, and directory_list_works as the tools for the adjacent jobs.
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?
Opens with concrete user phrasings ('lookup IPI 12345', 'find creator by MusicBrainz ID') and gives explicit when-not guidance: 'It does not accept a name: to find a creator by name... use directory_list_people (q) or directory_search first.' It also names the natural follow-up (directory_list_works), so both entry and exit routing are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'what's the ISWC for X?', 'who wrote X?', 'tell me about song X', 'is this song registered?'. Get the details of a single listed work by ISWC or work UUID. Returns the credits, one per person with each role marked confirmed or not confirmed by that person, and the person's IPI; each writer's share of the work, only when the owner chose to show shares AND that writer confirmed it themselves (with how many writers have); the recordings' ISRCs, audio analysis (BPM, key, energy) when the audio has been analysed, streaming links (Spotify, Apple Music, YouTube), AI origin (what the owner declared, with ACRCloud's detection beside it), the work's PICA score, and whether the owner is taking licensing enquiries, as a markdown summary. Fields with no data are omitted. → then: directory_lookup_person (a credited writer, by the credit's global_creator_id or IPI), directory_search_recordings (find similar tracks by audio)
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ISWC (e.g. T-123.456.789-0) or work UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, closed-world safety, and the description adds substantial behavioral detail: conditional disclosure rules for writer shares, confirmation status of credits, optional audio analysis fields, and omitted empty fields. It does not discuss rate limits or lookup failure behavior for an unknown ISWC/UUID, which keeps it just short of the top mark.
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?
Trigger phrases and the core action are front-loaded, and the follow-up routing is clearly set off with an arrow. The return-value enumeration is a single long run-on clause that would read better as a list, but given there is no output schema it largely earns its space.
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 output schema and a rich return payload, the description fully documents what comes back (credits, IPI, conditional shares, ISRCs, audio analysis, streaming links, AI origin, PICA score, licensing status) and how output is formatted. Nothing an agent needs to call or interpret it is missing.
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 identifier parameter already documents the ISWC format and UUID alternative, so the description's 'by ISWC or work UUID' merely restates the schema. No additional syntax, normalization, or fallback guidance is offered.
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 precise verb plus resource ('Get the details of a single listed work by ISWC or work UUID') and the 'single' scoping distinguishes it from sibling list/search tools such as directory_list_works and directory_search.
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?
Provides concrete user-question triggers ('what's the ISWC for X?', 'is this song registered?') that define when to select it, and explicitly routes follow-ups to directory_lookup_person for credited writers and directory_search_recordings for audio similarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'what's new in the directory mcp', 'what changed in the directory', 'directory release notes', 'what version is the directory on'. Returns recent releases of the PICA directory MCP server — what shipped in the public catalogue surface itself. NOT for catalogue content searches (use directory_search / directory_list_works / directory_chain for those). Returns { package, current_version, releases: [{ version, date, sections, markdown }], resource_uri }. Defaults to the last 3 releases; use since_version to bound the output or sections to filter to Added/Fixed/etc. → then: directory_search (explore anything a release note mentions)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of releases to return. Default 3, max 20. | |
| sections | No | Filter each release's sections to only these names (e.g. ['Added', 'Fixed']). Sections not in the list are omitted from output. | |
| since_version | No | If set, returns only releases strictly greater than this version (semver-compared). Versions equal to since_version are excluded. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds the return shape ({ package, current_version, releases: [...] }), the default of the last 3 releases, and that sections are omitted when filtered — useful context beyond the annotations, though the default cap is also repeated from 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?
Front-loaded with the use case, then the return shape, then filtering, then the next step — a clean progression. Slightly dense with the quoted trigger-phrase list and the inline JSON return signature, but every element serves selection or invocation.
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?
No output schema exists, yet the description spells out the return object and the default release count, and it covers filtering behavior and a follow-up tool. Nothing an agent needs in order to call this correctly is missing.
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 limit, sections, and since_version are already fully documented in the schema, including defaults, max, and semver-comparison behavior. The description only restates that since_version bounds output and sections filter Added/Fixed/etc., adding no new semantics.
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 and resource ('Returns recent releases of the PICA directory MCP server') and immediately scopes it to the public catalogue surface itself, not catalogue content. The explicit 'NOT for catalogue content searches (use directory_search / directory_list_works / directory_chain)' separates it from siblings without requiring schema inspection.
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?
Gives literal trigger phrasings, an explicit exclusion with the three sibling tools that handle the excluded case, and a follow-up route ('then: directory_search'). When-to-use, when-not-to-use, and alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'find me X', 'who or what is X?', 'find any record of X', 'a song about X'. Use when the entity type is not yet known. Convenience fan-out across works and creators — runs list_works and list_people with the same query and returns the union. No cross-type ranking; prefer list_works or list_people when the entity type is known. → then: directory_lookup_work (work details), directory_lookup_person (creator details, by the result's global_creator_id)
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Limit results to a specific entity type | |
| query | Yes | Search query — matches work titles, ISWCs, creator names, ISNIs | |
| human_made_only | No | Works only: keep works the owner declared human-made that ACRCloud does not call likely AI-generated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely new behavioral context: it is a fan-out of two underlying calls and results are NOT cross-type ranked — an ordering trait the annotations do not convey. It stops short of describing result caps or pagination, so not a 5.
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?
Front-loaded with the when-to-use triggers and the core fan-out behavior, and every sentence carries information. The quoted trigger-phrase list and arrow notation are slightly dense but efficient rather than wasteful.
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?
No output schema exists, and the description explains what comes back (the union of list_works and list_people results) and points to lookup tools for details. It leaves the exact result shape and any result limits unspecified, which is the main remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so query, type, and human_made_only are already fully documented. The description only implies that the same query is applied across both entity types; it adds no syntax or format detail beyond the schema, so baseline 3 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?
States a specific verb and resource ('convenience fan-out across works and creators') plus the implementation detail that it runs list_works and list_people and returns the union. This clearly distinguishes it from directory_list_works, directory_list_people, and the lookup_* 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?
Gives explicit trigger phrases ('find me X', 'who or what is X?') and the key selection condition: use when the entity type is not yet known, and prefer list_works or list_people when it is. It also routes forward to directory_lookup_work and directory_lookup_person for follow-up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'find upbeat tracks around 120 BPM', 'find instrumental tracks in C minor', 'find energetic music for sync', 'tracks at X BPM in [key]'. AUDIO-FEATURE search only — for name- or title-shaped queries use directory_lookup_work, directory_lookup_isrc, or directory_list_people, NOT this tool. Not for a theme or subject ('a song about love'): search that in directory_list_works q first, then narrow here. Few recordings carry a mood yet, so an empty mood search does not mean the directory has no such song. Find tracks by BPM, key, energy, danceability, duration, mood, and more. The measured filters (BPM, key, energy, …) match analysed audio only; a mood search also returns works whose owner set the mood, marked mood_note "mood set by the owner, not analysed" — say so when you present them. Only returns recordings of works listed on the directory by their owner or a confirmed writer. → then: directory_lookup_work (credits and licensing details for a matched track)
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Musical key (e.g. 'C', 'F#', 'Bb'). Matches the detected key. | |
| mood | No | Mood — one of: aggressive, ambient, calm, contemplative, dark, dramatic, dreamy, energetic, epic, ethereal, hopeful, intense, melancholic, nostalgic, passionate, playful, romantic, sad, tender, tense, triumphant, uplifting, warm. "happy" is read as "uplifting". Any other word is refused. A mood matches analysed recordings, and also listed songs whose owner set that mood on audio that is not analysed: those carry mood_note "mood set by the owner, not analysed" and no measured values. With a BPM, key, energy or other measured filter, only analysed recordings match. | |
| limit | No | Max results to return (default: 20, max: 100). | |
| max_bpm | No | Maximum BPM (e.g. 140) | |
| min_bpm | No | Minimum BPM (e.g. 100) | |
| key_mode | No | Key mode — major or minor | |
| max_energy | No | Maximum energy, 0 to 1 (measured loudness). | |
| min_energy | No | Minimum energy, 0 to 1 — measured loudness (ITU-R BS.1770 integrated loudness on a quiet-to-loud scale), not a mood. Higher = louder. | |
| vocals_only | No | Ignored: vocals are not measured and owners do not mark them. | |
| max_duration | No | Maximum duration in seconds. | |
| max_dynamics | No | Maximum dynamics, 0 to 1 (see min_dynamics). | |
| min_duration | No | Minimum duration in seconds. | |
| min_dynamics | No | Minimum dynamics, 0 to 1 — measured loudness range (EBU R128). Not yet calibrated: accepted and ignored until it is (the result's ignored_filters says so). | |
| max_brightness | No | Maximum brightness, 0 to 1 (measured). | |
| min_brightness | No | Minimum brightness, 0 to 1 — measured high-frequency content (spectral rolloff), not a mood. 0 = the darkest 5% of the directory, 1 = the brightest 5%. | |
| max_danceability | No | Ignored: danceability is not measured. | |
| min_danceability | No | Ignored: danceability is not measured. Use min_rhythmic_density or min_energy. | |
| instrumental_only | No | Only songs or recordings the OWNER marked instrumental (not a measurement). | |
| max_rhythmic_density | No | Maximum rhythmic density, 0 to 1 (see min_rhythmic_density). | |
| min_rhythmic_density | No | Minimum rhythmic density, 0 to 1 — measured onsets per second. Not yet calibrated: accepted and ignored until it is. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: empty mood searches are not evidence of absence, mood matches may be owner-set rather than analysed and must be labelled, and only recordings of works listed by the owner or a confirmed writer are returned. These are non-obvious result-semantics caveats an agent could not infer from 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?
Front-loads the trigger examples and the primary exclusion before caveats, and every sentence carries operational information. It is dense and slightly long, and the enumerated user-quote examples could be trimmed, but nothing is 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 20-parameter, zero-required tool with no output schema, the description covers coverage limits, mood caveats, and the follow-up tool, which is the important missing context. It stops short of describing result shape or pagination behaviour beyond the limit parameter, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents filter semantics in depth (including ignored filters and mood_note behaviour), so the description's parameter content is largely duplicative. It adds the useful framing that measured filters match analysed audio only, but it also advertises 'danceability' as a searchable facet even though the schema marks that parameter as ignored — a minor internal inconsistency. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('AUDIO-FEATURE search' of recordings by BPM, key, energy, duration, mood) and explicitly distinguishes itself from name/title searches by naming directory_lookup_work, directory_lookup_isrc, and directory_list_people. An agent can route without opening any 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?
Gives concrete user phrasings that trigger the tool, an explicit exclusion rule for title-shaped queries, an exclusion for theme/subject queries routed to directory_list_works, and a named next step (directory_lookup_work). When-to-use, when-not-to-use, and alternatives are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'ask the owner if I can license this', 'send a licensing enquiry for X', 'contact the rights holder about using this song'. Side effect: this SENDS AN EMAIL. It records a licensing enquiry for a work listed in the public directory and emails it to the work's owner, who can reply to the user by email (the user's address is shared with them); a confirmation email to the user is usually sent but not guaranteed. Nothing is agreed or priced: it only opens the conversation. This is the ONLY way to reach a listed work's owner: PICA never shares the owner's email address, so never draft the enquiry as an email for the user to send, and never guess an address. Sending through this tool is also what records the enquiry for the owner. ONLY call after the user has explicitly asked to send it and has given their own name, email and a description of the project. Never invent these, and never send on their behalf without asking. Get work_id from directory_lookup_work, directory_list_works or directory_chain. A 403 means the owner is not taking enquiries; a 404 means the work is not publicly listed; an unknown outcome means it may already have been sent, so never resend without asking. MORE WORKS FROM THE SAME OWNER: before sending, you may call directory_similar_from_owner and offer the user the owner's similar works. Put a work in also_work_ids ONLY if the user explicitly said yes to adding that work; never add works on your own judgement. All works go to the one owner in one enquiry (at most 10 in all); a work from another owner is refused. NOT FOR: looking up who owns a work (use directory_lookup_work). → first: directory_similar_from_owner (optional, to offer more of the owner's works) → then: directory_lookup_work (the work page and credits, to share with the user)
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | For how long (optional; omit if the user didn't say). | |
| work_id | Yes | The work's UUID from the directory. | |
| territory | No | Where it would be used (optional; omit if the user didn't say). | |
| budget_notes | No | Anything the user said about budget that isn't a single amount, e.g. a range. | |
| company_name | No | The user's company or production (optional). | |
| contact_name | Yes | The user's own name, as they gave it. | |
| project_type | Yes | The kind of project. | |
| also_work_ids | No | More works from the SAME owner to include, from directory_similar_from_owner, and only the ones the user explicitly agreed to add. Omit otherwise. | |
| budget_amount | No | Proposed fee, only if the user named one (optional). | |
| contact_email | Yes | The user's own email address. The owner will reply to it. | |
| budget_currency | No | Three-letter currency code (default GBP). | |
| project_description | Yes | How the music would be used, in the user's words. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations it discloses that an email is actually sent, that the user's address is shared with the owner, that a confirmation email is 'usually sent but not guaranteed', and that nothing is agreed or priced. It also documents failure semantics (403 = owner not taking enquiries, 404 = not publicly listed, unknown outcome = may already have been sent) and the 10-work cap with cross-owner refusal.
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?
It is front-loaded with user-facing trigger phrases and ordered from side effects to prerequisites to error handling. It is dense and mostly earns its length, though the trailing arrow-based call-order summary partially repeats guidance already stated earlier.
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 non-idempotent, externally-visible email-sending tool with 12 parameters and no output schema, the description covers side effects, consent requirements, identifier sourcing, multi-work constraints, and error interpretation. An agent has everything needed to call it safely.
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, but the description adds real meaning: where work_id comes from (lookup_work, list_works, chain), the rule that also_work_ids may only contain works the user explicitly agreed to, and the at-most-10 total across all works. It does not explain term/territory/budget fields, but the schema already covers those.
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 and resource: it records a licensing enquiry for a directory work and emails it to the owner. It also distinguishes itself from siblings by declaring it is 'the ONLY way to reach a listed work's owner' and explicitly excluding directory_lookup_work's purpose.
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 gives concrete trigger phrases, explicit preconditions (user must have asked and supplied name, email, project description), exclusions ('NOT FOR: looking up who owns a work'), and a suggested call order involving directory_similar_from_owner and directory_lookup_work. Alternatives and when-not-to-use are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'does this owner have anything similar?', 'any other songs like this from them?'. Typically while they are asking about licensing one song. Returns up to 9 of the SAME owner's other listed works that share this work's topics, genre or tempo, each with the reasons, and how many listed works the owner has in all. Never another owner's works. Nothing is sent: offer them to the user, and add any to directory_send_licensing_enquiry's also_work_ids only if the user explicitly says yes. Empty when the work is not listed or the owner is not taking enquiries. → then: directory_send_licensing_enquiry (with the user's go)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many to suggest (default 9). | |
| work_id | Yes | The work the user is asking about (UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint annotations, it discloses that nothing is sent, that each suggestion carries the reasons it matched, that the total listed-work count is returned, and the precise conditions for an empty result (work not listed or owner not taking enquiries). That is materially more than the annotations 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?
Front-loaded with the trigger and packed with decision-relevant detail, with no filler. The telegraphic fragments ('→ then:', 'with the user's go') are efficient but verge on run-on, costing a point on structure.
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 two-parameter read tool with no output schema, the description covers what comes back, the matching rationale, the empty-result conditions, and the exact next tool to call. Nothing an agent needs in order to call it and act on results is missing.
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 work_id and limit are already documented. The description only echoes the ceiling ('up to 9') without adding format or semantics the agent needs beyond the schema, so baseline 3 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?
States a specific verb and resource: returns up to 9 of the SAME owner's other listed works that share this work's topics, genre or tempo. It explicitly excludes another owner's works, so the agent can distinguish it from sibling lookups like directory_lookup_work or directory_search.
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?
Gives the exact user phrasings that should trigger it ('does this owner have anything similar?', 'any other songs like this from them?'), the typical context (they are asking about licensing), and the follow-up path: offer results, and only add to directory_send_licensing_enquiry's also_work_ids if the user explicitly says yes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'load a directory skill', 'use the sync brief method'. Call after directory_skill_list, to load the one skill the user's request matches (e.g. find-music-for-sync-brief). Returns the full methodology body for one directory skill — markdown with step-by-step instructions and tool chains. Call directory_skill_list first to see available skill names, then directory_skill_get to load one. Read once at the start of the workflow; do not re-fetch on every step. → then: directory_search (run the loaded methodology against the catalogue)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Kebab-case skill name from directory_skill_list (e.g. 'find-music-for-sync-brief'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent, and non-destructive annotations, it discloses the returned content and format and explains the intended one-time retrieval behavior within a workflow. It does not cover failure behavior for an invalid or stale skill name, but the operational context is otherwise useful.
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 triggers and purpose are front-loaded, and the workflow guidance is easy to follow. However, the requirement to call directory_skill_list first is stated twice, creating noticeable redundancy in an otherwise efficient description.
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 this single-parameter retrieval tool, the description supplies the prerequisite, selection rule, invocation frequency, downstream action, and a concrete example. Because there is no output schema, its explanation of the returned markdown methodology is especially valuable and makes the definition sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents name, including its kebab-case format, source, and example. The description adds the selection rule of choosing the single skill matching the user's request, although its remaining parameter guidance largely repeats the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool loads the full methodology body for one directory skill, including its markdown format and step-by-step contents. It distinguishes this retrieval role from directory_skill_list, which discovers names, and directory_search, which applies the loaded methodology.
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 gives explicit user-request triggers, requires directory_skill_list first, explains how to select the matching skill, and identifies directory_search as the next step. The instruction to read once and not re-fetch on every step also provides clear when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user asks: 'what skills do you have?', 'what can you do?', 'show me your methodologies', 'how do I find music here?'. Returns the list of downloadable directory skill methodologies — name, description, trigger phrases. Cheap to call. → then: directory_skill_get (load a specific skill's full methodology body)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds value by disclosing the shape of the returned list and flagging that the call is inexpensive, which tells the agent it can call speculatively. No pagination or size limits are mentioned, keeping it short of a 5.
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?
It is front-loaded with the triggering question set, then what comes back, then a cost signal, then an arrow-delimited next step. Every clause carries information an agent would otherwise have to infer; nothing is redundant with the title or annotations.
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-argument listing tool with no output schema, the description supplies everything needed: when to call, what fields come back, and where to go next. Nothing an agent needs in order to invoke this correctly is missing.
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, so there is no parameter meaning to add and the baseline of 4 applies. The description correctly implies a no-input call by presenting it purely as a listing operation.
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 ("list of downloadable directory skill methodologies") and even enumerates the returned fields — name, description, trigger phrases. It also explicitly separates this tool from directory_skill_get, so an agent can route between the two without inspecting either 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?
It names concrete user utterances that should trigger the call ("what skills do you have?", "show me your methodologies") and states the follow-up alternative: use directory_skill_get to load a specific skill's full methodology body. Both when-to-use and the next-step alternative are explicit.
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.
directory_chaindirectory_list_peopledirectory_list_worksdirectory_lookup_isrcdirectory_lookup_persondirectory_lookup_workdirectory_release_notesdirectory_searchdirectory_search_recordingsdirectory_send_licensing_enquirydirectory_similar_from_ownerdirectory_skill_getdirectory_skill_listmanage your music catalog through conversation — works, recordings, credits, agreements, royalties
Check a catalogue against The MLC, look up a song's writers, publishers and ISWC, validate CWR files
Find the songwriter behind a name or IPI name number, under every spelling and number.
Music search over 185M+ tracks: describe a sound, find similar songs, ISRC/ISWC lookup, beat grids.
Add one secure layer between your agents and this server.
