Find the songwriter behind a name or IPI name number, under every spelling and number.
Scored across 4 tools
find_songwriter (name) and get_songwriter (person ID) are clearly distinct, but check_writers and songwriter_by_ipi both map IPI name numbers to writers and differ mainly in batch size and detail level. An agent could plausibly pick the wrong one for a single-number lookup, though the descriptions do state the batch/single distinction.
All names use snake_case, and three follow a verb_noun pattern (check_writers, find_songwriter, get_songwriter). songwriter_by_ipi breaks the verb-first convention, but it remains readable and predictable.
Four tools is reasonable for a narrow songwriter-identity domain. However, check_writers and songwriter_by_ipi substantially overlap, so the set is slightly larger than strictly necessary.
The surface covers name-based search, person-ID detail, single-IPI lookup, and batch-IPI lookup, which addresses the core identity-resolution workflow. Minor gaps remain around retrieving a full works catalogue or searching directly by work/publisher, but the person page is noted as covering the rest.
Use when the user has several IPI name numbers, such as the writers on a song, a catalogue or a registration file, and wants to know who each one is, or whether some of a writer's works sit under another spelling or number. Up to 50 numbers per call. For each: the person holding it, their registered names, works in total and on their main number, works_elsewhere (registered only under another spelling or number), and a person_url.
| Name | Required | Description | Default |
|---|---|---|---|
| ipi_name_numbers | Yes | Up to 50 IPI name numbers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral detail: the 50-number batch limit and the exact return fields, including what works_elsewhere means. It does not explain error handling or the conflict with the schema's maxItems of 100, keeping it from 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 definition is front-loaded with the use case, followed by the limit and return fields in a compact sequence. Every sentence adds actionable 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 read-only batch lookup with no output schema, the description enumerates the key return fields and clarifies works_elsewhere, which is valuable. However, the 'Up to 50 numbers per call' statement conflicts with the schema's maxItems of 100 and no explanation is given, leaving a small completeness 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 the schema already documents the single ipi_name_numbers parameter. The description repeats the 50-number limit and gives input-context examples, but adds no syntax, format, or constraint detail beyond what the schema provides. 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 clearly states a batch lookup of songwriters by IPI name number and what each result contains. The plural 'several IPI name numbers' and 'Up to 50 numbers per call' distinguish it from singular siblings like get_songwriter and find_songwriter.
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 when to use the tool: when the user has several IPI name numbers, such as writers on a song, catalogue, or registration file. It does not name when not to use it or explicitly route single-number cases to a sibling, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when the user names a songwriter or composer and wants to know who they are, which person a name belongs to, or every registration of that writer. Returns the persons the name could be: each with a person ID, the names and IPI name numbers they are registered under, how many works, and a person_url to cite. Pairs listed under possibly_the_same_person were held apart and are not merged; why says why. Candidates are this lookup's own grouping, made afresh for the name, and can differ from the stored person that get_songwriter and the person page describe: a candidate can include records with no IPI name number that the stored person lists apart, and two candidates can carry the same person_id when this lookup keeps apart records the stored person joined. Each record's person_id is the stored person it belongs to, or null; person_records is how many records that person holds, and records_not_in_this_answer how many of them this candidate does not, because they sit in another candidate or outside this lookup. A candidate whose records belong to more than one stored person has no person_id and lists them in stored_persons, with a note: the stored records hold those registrations as different people. For a person's registrations as they stand, call get_songwriter. A candidate's works counts every record in it, records held apart from the person included; the person's own count is get_songwriter's works.total. Registrations are under legal names. When the user gives a professional or stage name and you know the writer's legal name, search the legal name first: a stage name usually returns other people whose names contain those words, not the writer. If the writer you expect is not among the candidates, or song_match.match is none, try their legal name. truncated means more registrations matched than one answer groups: a fuller name narrows it. Give a song title they wrote, when known, to say which of several namesakes wrote it. A one-word name is not searched: ask for the full name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The songwriter's full name, as registered or as commonly written | |
| song | No | Optional: the title of a song they wrote |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, while the description adds substantial behavioral context: candidates are grouped afresh for the lookup, possibly_the_same_person pairs are not merged, `why` explains separation, person_id may be null, stored_persons is used for multi-person candidates, and counts include records held apart. It also explains truncated results and legal-name registration behavior without contradicting the read-only annotation.
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 purpose and usage guidance are front-loaded, and much of the output caveat detail is relevant because there is no output schema. However, the description is an overlong, dense single paragraph with complex clauses and repeated discussion of get_songwriter and candidate grouping, making it harder to scan than necessary.
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?
There is no output schema, yet the description explains the returned candidate structure, person_id and stored_persons edge cases, person_records and records_not_in_this_answer counts, truncation meaning, and legal-name search behavior. This is enough for an agent to call the tool and interpret its results 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%, but the description adds meaning beyond the schema: registrations are under legal names, stage names usually return other people, legal names should be searched first, one-word names are not searched, and the optional song title is used to identify which namesake wrote a work. These are important semantic constraints not captured by the schema's basic 'full name' and 'song title' descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find a songwriter by name') and explains that it returns candidate persons with IDs, names/IPI numbers, works, and a citable URL. It explicitly contrasts itself with get_songwriter for stored registrations, so an agent can distinguish the main sibling.
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 triggers: use when the user names a songwriter/composer and wants to know who they are, which person a name belongs to, or every registration. It also states fallbacks and exclusions: search legal names before stage names, try legal name if the expected writer is absent, provide a song title to disambiguate namesakes, and ask for a full name when only a one-word name is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when you have a Songlinks person ID (SLP-XXXX-XXXX-X), from find_songwriter or a person page, and the user wants that writer's details: the registrations grouped into the person, records listed apart as possibly the same person, and their first works. Each record says how it was joined: main marks the record the ID was issued on, and rule is the evidence: same_ipi (another of the person's records carries the same IPI name number), ipi (it carries the person's own number), model (judged the same writer from works, co-writers and publishers in common; score is how sure), corroborated (confirmed by an independent source) or verdict (decided by a person). At most 25 works are listed; works.total is the full count and the person page lists the rest. works.ordered_by is recordings when the list starts with the most-recorded works, and coded when it is in catalogue-code order: then it is a sample, not the writer's best-known songs.
| Name | Required | Description | Default |
|---|---|---|---|
| person_id | Yes | A Songlinks person ID, SLP-XXXX-XXXX-X |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering the safety profile, the description adds real behavioral content: the 25-work listing cap with works.total holding the full count, and the meaning of works.ordered_by=coded being a sample rather than best-known songs. It stops short of auth, rate-limit, or error behavior, so it earns a 4 rather than 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 usage condition and ID format are front-loaded, so an agent gets the trigger immediately. The remaining text is dense and run-on, with nested clauses and backticked tokens packed into two long sentences, but almost every clause carries information the agent needs given the absent output schema.
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?
There is no output schema, so the description carries the full burden of describing returns, and it does so thoroughly, including the join-rule vocabulary (main, same_ipi, ipi, model with score, corroborated, verdict) and the listing-cap semantics. Combined with full parameter coverage, nothing an agent needs to call it 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 coverage is 100% and there is a single parameter whose format (SLP-XXXX-XXXX-X) is already documented in the schema. The description restates the same format without adding syntax, validation, or edge-case meaning, so the 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?
The description states a clear purpose: use it when you hold a Songlinks person ID and want that writer's details, then enumerates what comes back (registrations, records, first works). It implicitly routes from find_songwriter but never explicitly contrasts itself with songwriter_by_ipi or check_writers, so sibling differentiation is only partial.
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 an explicit precondition and ID source: a Songlinks person ID (SLP-XXXX-XXXX-X) obtained from find_songwriter or a person page. It does not state when *not* to use it or which sibling to prefer when the user has an IPI instead of a person ID.
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 has an IPI name number (up to 11 digits, often written without its leading zeros) and wants to know which songwriter holds it. Returns the person or persons holding the number, each with a person ID and person_url; use get_songwriter for one person's details. none means no person here holds it: it may be a publisher's number, or one whose registrations have not been grouped.
| Name | Required | Description | Default |
|---|---|---|---|
| ipi_name_number | Yes | One IPI name number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description adds genuinely non-obvious behavior: it can return multiple persons, each carries person_id and person_url, and `none` is a meaningful signal (publisher number or ungrouped registrations) rather than an error. It stops short of describing error/rate-limit behavior, but the not-found semantics are the important detail here.
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?
Three tight sentences, front-loaded with the trigger condition, then return shape, then the not-found case. Every clause carries information; nothing restates the title or the schema.
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 supplies the return shape (person(s) with person_id and person_url), the null-result semantics, and cross-tool routing. For a single-parameter lookup tool with a readOnly annotation, nothing needed to call it 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 coverage is 100%, so the baseline is 3, but the description adds format guidance the schema lacks: 'up to 11 digits, often written without its leading zeros'. That directly informs how an agent should normalize the value before calling, which the generic schema description 'One IPI name number' does not.
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?
Names a specific verb and resource ('find a songwriter by IPI name number') and explicitly scopes the input to an IPI name number. It also distinguishes itself from the sibling get_songwriter, so an agent can choose between them without opening 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?
'Use when the user has an IPI name number ... and wants to know which songwriter holds it' gives an explicit trigger condition. It goes further by naming the alternative ('use get_songwriter for one person's details') and by explaining the `none` outcome, so both the happy path and the fallback routing are covered.
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.
check_writersfind_songwriterget_songwritersongwriter_by_ipiPublic music-rights directory: who wrote and owns a song, its ISWC/ISRC/IPI, and licensing asks
Music search over 185M+ tracks: describe a sound, find similar songs, ISRC/ISWC lookup, beat grids.
Check a catalogue against The MLC, look up a song's writers, publishers and ISWC, validate CWR files
Find engineers and scientists from papers, open source and patents. Each result links its sources.
Add one secure layer between your agents and this server.