directory_chain
ChatGPTUse 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)
directory_list_people
ChatGPTUse 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)
directory_list_works
ChatGPTUse when the user asks: 'list works in PICA', 'works starting with B', 'find works by publisher X', 'browse the catalog'. 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 songs the owner declared human-made that ACRCloud does not call likely AI. → then: directory_lookup_work (full details with credits and audio)
directory_lookup_isrc
ChatGPTUse 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)
directory_lookup_person
ChatGPTUse 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)
directory_lookup_work
ChatGPTUse 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 song, 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)
directory_release_notes
ChatGPTUse 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)
directory_search
ChatGPTUse when the user asks: 'find me X', 'who or what is X?', 'find any record of 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)
directory_search_recordings
ChatGPTUse 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. 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 songs 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 songs listed on the directory by their owner or a confirmed writer. → then: directory_lookup_work (credits and licensing details for a matched track)
directory_send_licensing_enquiry
ChatGPTUse 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 song'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 SONGS FROM THE SAME OWNER: before sending, you may call directory_similar_from_owner and offer the user the owner's similar songs. Put a song in also_work_ids ONLY if the user explicitly said yes to adding that song; never add songs on your own judgement. All songs go to the one owner in one enquiry (at most 10 in all); a song from another owner is refused. NOT FOR: looking up who owns a song (use directory_lookup_work). → first: directory_similar_from_owner (optional, to offer more of the owner's songs) → then: directory_lookup_work (the work page and credits, to share with the user)
directory_similar_from_owner
ChatGPTUse 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 songs that share this song's topics, genre or tempo, each with the reasons, and how many listed songs the owner has in all. Never another owner's songs. 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 song is not listed or the owner is not taking enquiries. → then: directory_send_licensing_enquiry (with the user's go)
directory_skill_get
ChatGPTUse 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)
directory_skill_list
ChatGPTUse 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)
