setlist-mcp provides tools to search and explore concert setlists, artists, venues, cities, and users on setlist.fm, plus authenticated attendance actions.
Artists — search by name or MusicBrainz ID, retrieve artist profiles, and list an artist's setlists.
Setlists — search by any combination of artist, venue, city, country, tour, date, or year; fetch full setlist details by ID (songs, encores, covers, guest performers); retrieve historical versions.
Venues — search by name/location, get venue details, and list all setlists performed at a venue.
Cities & Countries — search cities by name/location, get city details by geoId, and list all countries supported by setlist.fm.
Users — get a user's public profile, view concerts they've attended, and see setlists they've created or edited.
Bulk concert resolution — resolve up to 24 concerts (artist + date + optional city/venue) to their setlists in a single call.
Attendance tracking (authenticated) — mark or unmark concerts as attended on your setlist.fm account, with a dry-run preview mode before committing.
Utility — extract a setlist ID from a setlist.fm URL, and run a healthcheck to verify your API key and connectivity.
Click on "Install 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., "@setlist-mcp What was the setlist for Nirvana's last show?"
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.
MCP server for setlist.fm — search concert setlists, artists, venues, tours, and cities from Claude via natural language. Mostly read-only (the setlist.fm REST API exposes no write endpoints), plus authenticated "I was there" attendance actions via your logged-in session.
This project was developed and is maintained by AI (Claude). Use at your own discretion.
Exposes 20 tools — 18 read-only over the setlist.fm REST API, plus 2 authenticated "I was there" attendance actions:
Area | Tools |
Artists |
|
Setlists |
|
Venues |
|
Cities & countries |
|
Users |
|
Resolve |
|
Attendance (authenticated writes) |
|
Utility |
|
Related MCP server: MusicBrainz MCP Server
Get a free API key (non-commercial use) at setlist.fm/settings/api, then add the server to your .mcp.json:
{
"mcpServers": {
"setlist": {
"command": "npx",
"args": ["-y", "setlist-mcp"],
"env": {
"SETLIST_API_KEY": "your-api-key-here"
}
}
}
}Optional: SETLIST_ACCEPT_LANGUAGE (one of en, es, fr, de, pt, tr, it, pl) localizes city/country names.
See skills/setlist/SKILL.md for from-source setup, the full tool reference, and example flows.
Use is governed by the setlist.fm API terms. In short:
Attribute setlist.fm. Every result carries a url; surface it as a followable source link (no nofollow) wherever the data is shown. The tool descriptions instruct the model to do this, and results pass the url through verbatim.
Non-commercial only under a free key — commercial use requires setlist.fm's permission.
No persistent caching — this server makes a live API call per tool invocation and keeps no datastore. Please don't add one.
Keep your API key private — it lives in SETLIST_API_KEY (.env is gitignored) and never appears in tool output.
npm install
npm run build # tsc + esbuild bundle → dist/
npm test # tsc typecheck + vitestFor local runs, put SETLIST_API_KEY=<key> in a .env file (gitignored) next to the project root.
See CLAUDE.md for architecture, conventions, and gotchas.
MIT
Get a setlist.fm artist by their MusicBrainz ID (mbid). Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| mbid | Yes | Artist's MusicBrainz ID (mbid) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, so the tool is safe. Description adds behavioral details about the url field and attribution requirements, adding value beyond the 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?
Two sentences, no fluff, front-loaded with purpose. Every sentence is 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?
For a simple lookup tool with one parameter and no output schema, the description provides sufficient context about what is returned and how to handle missing data.
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%; the description does not add meaning beyond what the schema already provides for the 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?
The description clearly states the action (Get a setlist.fm artist) and the identifier (MusicBrainz ID). It distinguishes from sibling tools like setlist_get_artist_setlists and setlist_search_artists.
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 explicit guidance on attribution and linking when presenting results. Does not explicitly state when not to use or mention alternatives, but the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an artist's setlists (most recent first) by their MusicBrainz ID (mbid). Paginated via p. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| mbid | Yes | Artist's MusicBrainz ID (mbid) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), description adds pagination behavior via 'p' parameter, ordering (most recent first), and crucial attribution requirements (clickable source link, fallback URL). This fully discloses relevant behavioral traits.
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 sentences, no wasted words. First sentence gives core purpose, second adds pagination and URL inclusion, third addresses attribution. Front-loaded and efficient.
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 no output schema, description covers results contain URL and how to handle attribution. It mentions pagination and ordering. It could mention other typical fields (date, venue) but is sufficient for a simple list endpoint.
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% with descriptions for both parameters. The description adds value by linking pagination to the 'p' parameter, clarifying default page number, and noting the URL attribute in results.
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?
Description clearly states the verb 'Get' and the resource 'artist's setlists' with ordering 'most recent first'. It distinguishes from siblings by specifying the use of MusicBrainz ID (mbid) and the specific resource type.
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?
Description tells when to use (when you have an artist's mbid and need setlists) but does not explicitly state when not to use or list alternative tools. However, the context of sibling tools provides implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a city by its geoId. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| geoId | Yes | City's geoId |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds meaningful behavioral context: results include a url requiring attribution, and a fallback link. This goes beyond safety to address data presentation requirements.
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 efficient sentences: first states purpose and key return field, second provides essential citation instructions. No redundancy or 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 simple get tool with one parameter and no output schema, the description covers input, purpose, and a key output attribute. It could list additional return fields for completeness but is still adequate.
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?
With 100% schema description coverage (geoId described as 'City's geoId'), the description does not add new meaning beyond 'by its geoId'. Baseline score of 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 the tool gets a city by its geoId, which is a specific verb-resource pair. It distinguishes from sibling tools like setlist_search_cities by specifying the use of a geoId identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a geoId is known, and provides a clear citation requirement for presenting results. However, it lacks explicit guidance on when not to use this tool versus alternatives like searching cities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a setlist.fm setlist by its ID, including the full song list and event details. A setlist's songs live in sets.set[]; each set may have an encore number (1 = first encore) and a name (e.g. an acoustic set or a full album). Each song may carry: tape: true (pre-recorded intro/outro/interlude — not actually performed), cover (the original artist when it is a cover), with (a guest performer), and info (a note like "acoustic" or "first time live"). Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| setlistId | Yes | Setlist ID (e.g. 63de4613) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so description adds value by detailing data structure (sets, encores, song attributes) and attribution rules. No contradictions; description enriches behavioral understanding.
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?
Efficient and well-structured: first sentence states core purpose, then explains nested data format, and ends with attribution note. No redundant sentences; each 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 GET tool with one parameter and no output schema, the description covers response structure, optional fields, and usage instructions (attribution). Sufficient for an AI agent to invoke and present 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 description coverage is 100% (single parameter 'setlistId' documented). Description simply says 'by its ID', adding no new meaning beyond schema. 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?
Description clearly states 'Get a setlist.fm setlist by its ID, including the full song list and event details.' It specifies the verb ('Get'), the resource ('setlist'), and the method (by ID), effectively distinguishing from sibling tools that handle other entities or searches.
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 guidance on interpreting response fields (sets, songs, attributes) and attribution requirements (cite URL, fallback to setlist.fm). While it does not explicitly state when not to use this tool vs alternatives, the sibling tools are clearly for other entities, making usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific historical version of a setlist by its version ID. Setlists are wiki-edited; each edit has a version ID returned in a setlist's versionId field. A setlist's songs live in sets.set[]; each set may have an encore number (1 = first encore) and a name (e.g. an acoustic set or a full album). Each song may carry: tape: true (pre-recorded intro/outro/interlude — not actually performed), cover (the original artist when it is a cover), with (a guest performer), and info (a note like "acoustic" or "first time live"). Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| versionId | Yes | Setlist version ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds significant behavioral context: the wiki-editing nature of setlists, the structure of response fields (sets, songs, attributes like tape, cover, with, info), and important attribution requirements (clickable url, no nofollow, fallback link).
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 longer but every sentence adds value: purpose, source of versionId, response field explanations, and attribution rules. It is front-loaded with the action, making it clear and purposeful.
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 the single parameter, no output schema, and complex response structure, the description thoroughly covers what the agent needs to know: how to call the tool, interpret the result, and present it with proper attribution. No gaps are evident.
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 describes the `versionId` parameter as 'Setlist version ID' (100% coverage). The description adds valuable context by explaining that version IDs come from a setlist's `versionId` field, aiding the agent in obtaining the correct value.
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 retrieves a specific historical version of a setlist by its version ID. It uses a specific verb and resource, and distinguishes from siblings like `setlist_get_setlist` (current version) and search tools.
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 explains when to use the tool (to get a historical version via versionId) and how to obtain the versionId (from a setlist's `versionId` field). It does not explicitly mention when not to use it or name alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a setlist.fm user's public profile by their userId (their setlist.fm username). Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | setlist.fm userId (username) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds important behavioral context: results include a URL that must be presented as a clickable source with followable attribution. Also specifies fallback attribution when URL is absent. No contradictions.
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 sentences: first states the core function, second adds necessary attribution instructions. No wasted words, front-loaded for quick understanding.
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 single-parameter read-only tool, the description adequately covers purpose, input, and output attribution. Could mention that the output includes a user profile object, but the lack of output schema makes this acceptable.
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 covers 100% of parameters with 'userId' described as 'setlist.fm userId (username)'. Description restates this without adding extra semantic detail, so baseline score of 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?
Clearly states the tool retrieves a setlist.fm user's public profile by their username. Distinguishes from sibling tools like setlist_get_user_attended or setlist_get_user_edited which have 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?
Implied usage: use to get a user's public profile. No explicit guidance on when not to use or alternatives, but the context of siblings shows differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the concerts a setlist.fm user has marked as attended. Paginated via p. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| userId | Yes | setlist.fm userId (username) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by explaining pagination behavior and attribution requirements. No contradictions. Additional details like the fallback link enhance transparency beyond 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?
Four concise sentences: purpose, pagination, attribution rule, fallback. Every sentence adds value; no wasted words. Front-loaded with main action.
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?
Covers key aspects: pagination, URL attribution, fallback. Does not explicitly describe the return format (e.g., array of setlist objects) but it's inferable. For a two-param read tool, this is nearly 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?
Schema coverage is 100% with both parameters described. The description does not add extra meaning beyond the schema (e.g., it mentions pagination but doesn't elaborate on `p` format). 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 'Get the concerts a setlist.fm user has marked as attended,' specifying verb (get) and resource (concerts). It distinguishes from sibling tools like setlist_get_user_edited and setlist_get_user by focusing on attended concerts.
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 guidance on pagination via `p` and detailed attribution instructions for the returned URL (clickable, no nofollow, fallback). However, it does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the setlists a setlist.fm user has created or edited. Paginated via p. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| userId | Yes | setlist.fm userId (username) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by disclosing that results include a URL and specifying attribution rules (no nofollow, fallback URL). This goes beyond annotations without contradiction.
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 two sentences long, front-loading the core purpose and then providing key usage details. No unnecessary words; every sentence adds value.
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 no output schema, the description adequately covers the return value by highlighting the URL field and attribution. However, it does not detail other potential fields in the paginated setlist results, which could be more 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?
Both parameters (userId and p) are described in the schema with 100% coverage. The description adds meaning by explaining that 'p' enables pagination and mentions that results include URLs, providing context beyond the schema's basic 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?
The description clearly states the verb 'get' and the resource 'setlists a setlist.fm user has created or edited', distinguishing it from sibling tools like setlist_get_user (user info) and setlist_get_user_attended (attended setlists).
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 explains pagination via parameter 'p' and provides attribution requirements for output URLs. However, it does not explicitly state when to use this tool versus alternatives like setlist_get_user_attended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a setlist.fm venue by its ID. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| venueId | Yes | Venue ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds important behavioral context: results include a url and require clickable attribution. This adds value for the agent.
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 concise sentences with no wasted words. The purpose and key behavioral note are front-loaded.
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 get tool with one parameter and no output schema, the description adequately covers the ID-based retrieval and attribution requirement. It does not list all returned fields, but that is acceptable.
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 description simply repeats 'by its ID'. Baseline 3 is appropriate as no extra parameter detail is added beyond 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 the tool retrieves a venue by ID using a specific verb and resource. It does not explicitly differentiate from siblings like setlist_get_venue_setlists, but the singular resource is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a venue ID is available, but provides no guidance on when not to use this tool or mention of alternatives. The attribution instruction is a usage note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get setlists performed at a venue, by venue ID (most recent first). Paginated via p. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| venueId | Yes | Venue ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by detailing pagination, ordering (most recent first), and the presence of a `url` field. It also clarifies the attribution requirement. No contradictions.
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 sentences: first states purpose and pagination, second gives critical attribution instruction. No wasted words, front-loaded with essential information.
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 paginated listing tool with 2 parameters and no output schema, the description adequately covers how to use it (venue ID, pagination) and what to expect (results with url, order). It lacks details on other possible fields but is sufficient.
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 describes both parameters. The description adds context that `p` is for pagination (already in schema) and that results include a url. This adds some value but does not significantly surpass the schema's baseline.
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 retrieves setlists performed at a venue by venue ID, with results ordered most recent first. It distinguishes itself from siblings like setlist_get_venue (venue details) and setlist_get_artist_setlists (by artist).
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 explicit instruction on pagination via `p` and mandates attribution by citing a clickable source link. Does not explicitly list when not to use or alternatives, but sibling context implies its specific use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm the API key is configured and works by calling the setlist.fm countries endpoint. Reports {ok, authenticated, country_count} with a plain-English hint distinguishing "no key" vs "bad key" vs "API error". Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by specifying the endpoint, output structure, and error distinctions. It confirms read-only nature consistent with annotations. No contradictions.
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 sentences, front-loaded with purpose, includes output structure. No wasted words; every sentence is informative.
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 no parameters, simple behavior, and rich annotations, the description fully covers the tool's functionality. Output is described adequately without needing an output schema.
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?
No parameters exist, and schema coverage is 100%. The description does not need to add parameter info. Baseline score of 4 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 the tool's purpose: confirming API key and connectivity by calling the setlist.fm countries endpoint and reporting specific fields. It distinguishes itself from sibling tools (data retrieval) by being a health check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying API configuration before other operations, but does not explicitly state when to use or alternatives. However, the context of sibling tools makes the purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse the setlist ID out of a setlist.fm setlist URL so you can paste a link instead of hunting for the ID. Returns {setlistId} (the trailing hex token before .html), ready to feed into setlist_get_setlist / setlist_mark_attended. Scoped to /setlist/ pages — artist (/setlists/) and venue (/venue/) URLs are rejected. Tolerates http/https, with/without www, trailing slash, query/fragment, and a missing .html. Pure local parsing — no network call. Errors if no ID can be parsed.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | A setlist.fm setlist URL, e.g. https://www.setlist.fm/setlist/.../...-4ba8a766.html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds substantial behavioral detail: tolerates various URL formats (http/https, www, trailing slash, query/fragment, missing .html), pure local parsing, and error condition if no ID parsed. No contradiction with 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?
Four sentences, each earning its place. The first sentence immediately conveys the core purpose. No redundant information. Efficiently structured with front-loaded key action.
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 parsing tool with one parameter, complete annotations, and no output schema, the description fully covers purpose, usage, parameters, behavior, and return format ('Returns {setlistId}'). No gaps remain.
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% with a single 'url' parameter described. The description adds value by providing an example URL format and specifying tolerances (http/https, with/without www, etc.), going beyond the schema's basic description.
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 explicitly states the tool parses a setlist ID from a setlist.fm URL and returns it as {setlistId}. It clearly distinguishes from sibling tools which likely expect an ID directly, not a URL.
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 explicit when-to-use: 'paste a link instead of hunting for the ID' and identifies downstream tools (setlist_get_setlist / setlist_mark_attended). It also specifies what URLs are rejected (artist/venue) and that it is pure local parsing with no network call, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record on YOUR setlist.fm account that you attended a show — the site's "I was there" marker — by setlist ID. Authenticated via your session (needs SETLIST_SESSION_COOKIE). Idempotent: a no-op if already marked. Without confirm: true it returns a dry-run preview and makes NO change; with confirm: true it toggles attendance and verifies by re-reading your attended list. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually record attendance; omit for a dry-run preview. | |
| setlistId | Yes | Setlist ID (e.g. from setlist_search_setlists / resolve_concerts) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses idempotency (matches annotation), dry-run preview, verification step after confirm, and authentication requirement. Goes beyond annotations by explaining the verification and attribution requirements.
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?
Concise yet thorough: each sentence adds value (purpose, auth, idempotency, dry-run, verification, result handling, attribution). No redundant or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple toggle tool with annotations. Explains return value (url with attribution), authentication, idempotency, and dry-run. No missing aspects.
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?
Adds context to both parameters: setlistId source (from search/resolve) and confirm flag behavior (dry-run vs. actual). Schema coverage is 100%, so baseline 3; description adds meaningful enhancement.
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?
Description clearly states the tool records attendance on the user's account, uses setlist ID, and distinguishes from siblings like setlist_unmark_attended. It specifies authentication via session cookie and the dry-run vs. confirm behavior.
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?
Explicitly states when to use: to mark attendance, with dry-run preview option. Provides context on idempotency and confirmation flag. Lacks explicit when-not-to-use but gives sufficient guidance for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve many concerts to their setlists in ONE call (instead of 2+ per show). Given up to 24 {artist, date, city?, venue?}, returns the best-match setlist for each — {setlistId, url, eventDate, artist, venue, city, tour, songCount, hasSongs} — plus a {matched, stubs, tourReferenced, unmatched, pending} summary. For each: searches artist + date (narrowed by your city/venue), and on a miss falls back to a relevance artist lookup (by mbid) and a punctuation-normalized name so format variants still resolve. hasSongs: false flags an empty stub page (no songs logged on setlist.fm). When a show is a stub, if the act toured a repeating set the result also includes a tourReference — a populated setlist from the SAME tour on a different date (with songs + its own url), clearly labeled as a reference, NOT this exact show (set tourFallback: false to skip these extra lookups). Calls are paced to setlist.fm's ~2 req/sec limit; if a big batch can't finish within the time budget the rest come back pending: true (re-call with just those) rather than timing out. Keep batches ≤24. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| concerts | Yes | Concerts to resolve (1–24 per call) | |
| tourFallback | No | For empty stubs, also fetch a same-tour reference setlist (default true). Set false to skip the extra lookups. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true. The description adds substantial behavioral context: rate limiting with pending results, fallback to artist lookup, tour reference behavior, attribution requirements, and stub handling. No contradictions with 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 description is front-loaded with the core purpose and each sentence adds necessary detail. Slightly long but justified given complexity. Would benefit from slight trimming, but still well-structured.
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 the complexity of the tool (batch resolution, stubs, tour references, rate limiting, attribution), the description covers all essential aspects. No output schema, but output fields are enumerated. Completeness is high for the tool's complexity.
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 baseline is 3. The description adds meaning beyond schema: explains the purpose of each input field, defaults for tourFallback, and batching limits. Adds value but not essential for understanding due to thorough schema 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?
The description clearly states it resolves multiple concerts to setlists in one call, reducing redundant API calls. It specifies input (up to 24 {artist, date, city?, venue?}) and output fields, effectively distinguishing from siblings like setlist_get_artist_setlists which handles single artist lookups.
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 to use this for batch resolution ('instead of 2+ per show') and mentions usage limits (≤24, pacing to 2 req/sec). It does not explicitly state when not to use, but context with sibling tools implies alternatives. Clear guidance on when to use given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search setlist.fm for artists by name or MusicBrainz ID. Returns matching artists with their MusicBrainz ID (mbid) — use that mbid with setlist_get_artist or setlist_get_artist_setlists. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| sort | No | Sort order (sortName = default, or relevance) | |
| artistMbid | No | Artist's MusicBrainz ID (mbid) | |
| artistName | No | Artist name to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, consistent with a search. Description adds value: results include a url with specific attribution rules (followable, no nofollow). No behavioral contradictions.
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 sentences, front-loaded with purpose. Each sentence adds value (purpose, usage guidance, attribution). No wordiness.
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 4 params with full schema coverage, readOnly annotation, and no output schema, the description covers purpose, result usage, and attribution. Could mention pagination or result format but sufficient for agent understanding.
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%, baseline 3. Description adds context by clarifying the purpose of artistMbid and relating it to other tools, though it largely restates schema fields. Still provides useful parameter usage guidance.
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?
Clearly states the tool searches setlist.fm for artists by name or MusicBrainz ID. Distinct from siblings by specifying it returns mbid for use with other tools.
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 clear context on when to use (searching artists) and how to use results (use mbid with get endpoints). Includes attribution requirements. No explicit when-not-to-use or alternatives, but sibling differentiation is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search setlist.fm for cities by name and/or location. Returns cities with their geoId — use it as cityId in setlist_search_setlists / setlist_search_venues, or with setlist_get_city. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| name | No | City name | |
| state | No | State the city lies in | |
| country | No | City's country | |
| stateCode | No | State code the city lies in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the readOnlyHint annotation, such as the attribution requirement and linking to setlist.fm. It discloses the return of a URL that must be cited, filling gaps not covered by 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 description is concise and well-structured, with the core purpose in the first sentence. It includes necessary details without being overly verbose, though minor redundancy could be trimmed.
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 the tool has 5 optional parameters and no output schema, the description adequately covers what the tool returns (geoId, url) and how to use the results. It addresses attribution and linkage, making it sufficiently complete for an agent to use 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 baseline is 3. The description provides context on using parameters for search by name/location but does not add significant new meaning beyond the schema 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?
The description clearly states the tool searches for cities by name and/or location, and explains the return of geoId for use in other tools. It distinguishes itself from sibling tools like setlist_get_city and other search functions.
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 explicit guidance on using the returned geoId in other tools and mentions attribution requirements for URLs. However, lacks explicit mention of when not to use this tool, though context from sibling tools implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all countries supported by setlist.fm, with their ISO country codes. Use a code as countryCode in setlist_search_setlists. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true; description adds that results include a URL, and specifies that attribution must be followable (no nofollow), plus fallback URL. Provides critical behavioral context beyond 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?
Three sentences, each serving a purpose. Slightly verbose in the citation instruction but remains clear and well-structured.
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 no parameters and no output schema, the description fully covers usage, purpose, and citation behavior. No gaps.
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?
Input schema has no parameters and description coverage is 100% (trivially). No parameter info needed, but description adds no semantics about nonexistent params.
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?
Clearly states it lists all supported countries with ISO codes, and explicitly links to the sibling tool setlist_search_setlists for using the codes. Differentiates well from siblings by being a reference list.
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?
Explains when to use (to obtain countryCode for setlist_search_setlists) and provides attribution requirements. Lacks explicit 'when not to use', but purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search setlist.fm for concert setlists. Filter by any combination of artist, venue, city, country, tour, date, or year (provide at least one). Combine filters to disambiguate — artistName + date can span multiple cities, so add cityName/cityId or venueName/venueId to pin the exact show. Omit the artist and pass venueName/venueId + date to list EVERY performer at a venue or festival that day. Every result includes songCount, setCount, and hasSongs, so you can skip empty 'stub' setlists (hasSongs: false) without a second fetch. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| date | No | Event date, ISO yyyy-MM-dd (e.g. 2025-08-28) | |
| year | No | Event year | |
| state | No | State name | |
| cityId | No | City's geoId | |
| venueId | No | Venue ID | |
| cityName | No | City name | |
| tourName | No | Tour name | |
| stateCode | No | State code | |
| venueName | No | Venue name | |
| artistMbid | No | Artist's MusicBrainz ID (mbid) | |
| artistName | No | Artist name | |
| countryCode | No | Country code (ISO 3166-1 alpha-2) | |
| lastUpdated | No | Only setlists updated on/after this UTC time, ISO yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds valuable behavioral context: every result includes songCount, setCount, hasSongs for skip logic, and attribution requirements. No contradictions.
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 the core purpose, then provides detailed usage guidance in a well-structured manner. Every sentence is informative and earns its place, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, no required fields, no output schema, the description is comprehensive: it explains result fields, attribution, stubs, and filter combination strategies. The agent has all necessary context.
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 has 100% coverage, but description adds significant semantic context beyond parameter definitions, such as how to combine filters, omit artist, and interpret result fields. This adds high value.
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 it searches for concert setlists on setlist.fm, with specific filtering capabilities. It distinguishes from sibling tools like setlist_search_artists or setlist_get_artist_setlists by focusing on setlists themselves.
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 explicit guidance on when to use, including minimum filter requirements, combining filters for disambiguation, and omitting artist to list performers. Also advises on handling stubs and attribution, effectively guiding the agent on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search setlist.fm for venues by name and/or location. Returns matching venues with their venue ID — use it with setlist_get_venue or setlist_get_venue_setlists. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| p | No | Result page number (defaults to 1) | |
| name | No | Venue name | |
| state | No | State name | |
| cityId | No | City's geoId | |
| country | No | Venue's country | |
| cityName | No | City the venue is in | |
| stateCode | No | State code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint: true; the description adds important behavioral context about attribution requirements (followable links, nofollow prohibition, fallback URL). It does not detail pagination or rate limits, but the core behavior is well explained.
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 only three sentences: first states the core action, second gives usage flow, third details attribution. Every sentence is essential and no filler. Front-loaded with the primary 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?
The description covers the search purpose, connection to other tools, and attribution rules. It mentions that results include a venue ID and url, but does not describe the full return structure (e.g., array of results, other fields). Given no output schema, slightly more detail on the response format would be helpful, but it's still mostly 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?
Schema coverage is 100% with clear parameter descriptions for all 7 fields. The description does not add new semantic information beyond referencing search by name and/or location, which is already implied by the schema. So the description adds minimal value over 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 the tool searches for venues by name and/or location and returns venue IDs. It distinguishes from siblings by explicitly mentioning integration with setlist_get_venue and setlist_get_venue_setlists, making its role in the workflow obvious.
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 tells when to use the tool (when you need to find a venue to then pass its ID to get_venue or get_venue_setlists) and provides attribution guidelines. It does not explicitly compare to other search tools like setlist_search_artists, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a show from YOUR attended list on setlist.fm, by setlist ID (reverses setlist_mark_attended). Authenticated via your session. Idempotent: a no-op if not currently attended. Without confirm: true it returns a dry-run preview and makes NO change; with confirm: true it removes the attendance and verifies by re-reading. Results include a setlist.fm url; when you present this data, cite it as a clickable source link to setlist.fm (their API terms require followable attribution — no nofollow). If a result has no url, link to https://www.setlist.fm instead.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be true to actually remove attendance; omit for a dry-run preview. | |
| setlistId | Yes | Setlist ID to remove from your attended shows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations: it mentions idempotency explicitly ('Idempotent: a no-op if not currently attended'), the dry-run vs confirm behavior, authentication via session, and attribution requirements. Annotations already included destructiveHint and idempotentHint, so the description enriches context.
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?
Concise at 4 sentences, front-loaded with purpose. Every sentence earns its place including the attribution note. No wasted words, though slightly dense.
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 the tool is simple with 2 parameters and no output schema, the description covers input behavior, idempotency, dry-run, authentication hint, and attribution. It provides sufficient context for an agent to use the tool correctly without additional queries.
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 description adds meaning: explains that confirm must be true for actual removal (otherwise dry-run preview) and setlistId is the identifier. This clarifies parameter behavior beyond schema 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?
The description clearly states the action ('Remove a show from YOUR attended list'), the resource ('setlist.fm'), and the reverse relationship ('reverses setlist_mark_attended'). It specifies the setlist ID parameter and distinguishes from sibling tools like mark_attended.
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 explicit usage context: it's the reverse of mark_attended, and explains the confirm parameter for dry-run or actual removal. While it doesn't explicitly state when not to use or compare to all siblings, it's clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose, targeting different resources (artist, setlist, venue, city, user) or actions (get, search, mark, unmark, resolve). No overlap.
All tools follow a consistent 'setlist_<verb>_<noun>' snake_case pattern throughout, making it easy to predict tool names.
20 tools is on the higher end but reasonable for a comprehensive API wrapper covering artists, setlists, venues, cities, users, search, and attendance management. Each tool is well-scoped.
The tool set covers the full lifecycle of querying setlist.fm data: searching, getting details, managing user attendance, resolving concerts, and health checks. No obvious gaps for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
setlist.fm: concert setlists by artist/venue/date. Free key required.
Specialist tools for any job — a lead, an image, a song, live data, and more.
Live festival data for AI agents: lineups, set times, dates, locations and ticket links worldwide.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrischall/setlist-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server