Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the description need not restate that. It adds valuable behavioral guidance: results include a setlist.fm URL, and the agent must present it as a clickable source with followable attribution (no nofollow), falling back to a base URL when missing. This goes beyond the schema and annotations, covering a non-obvious requirement.

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 with zero redundancy: the first states the core function, the second delivers the critical attribution instruction. Information is front-loaded and every clause earns its place, making the description easy to parse quickly.

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-by-ID tool with two parameters and no output schema, the description covers the primary use case and the one special presentation requirement (attribution). It does not enumerate all response fields, but the absence of an output schema is mitigated by the tool's simplicity and the mention of the key URL field.

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 fully describes both parameters (mbid and view) with 100% coverage, so the description adds no parameter-level meaning. The tool description does not elaborate on the view parameter, but the schema already explains its enum and behavior, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Get') and resource ('a setlist.fm artist') with a precise identifier (MusicBrainz ID). This distinguishes it from sibling tools like setlist_search_artists (search by name) and setlist_get_artist_setlists (fetch setlists), leaving no ambiguity about what the tool does.

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 establishes clear context: use this when you have an artist's MusicBrainz ID and need artist details. It does not explicitly name alternatives or exclusion criteria (e.g., 'if you don't have an mbid, use setlist_search_artists'), but the purpose is unambiguous enough that an agent can infer the appropriate scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses useful behaviors: result ordering, pagination, the presence of a setlist.fm url, and a concrete attribution policy including a nofollow restriction and fallback URL. It does not describe response fields or error behavior, but the annotation already covers the read-only safety profile.

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 deliver the core purpose, pagination behavior, and a required attribution rule with no filler. The most important information is front-loaded, and every sentence 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?

The description is sufficient for invoking the endpoint correctly, but since there is no output schema, it does not document the setlist object shape beyond the presence of a url. An agent presenting setlist data might need details like date, venue, or set content, which are not covered.

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 mbid, p, and view adequately. The description adds no new parameter-level semantics beyond reiterating that mbid is the lookup key and p controls pagination, so the 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 starts with a specific verb and resource: 'Get an artist's setlists' by MusicBrainz ID, and specifies ordering (most recent first). This clearly distinguishes it from sibling tools like setlist_search_setlists and setlist_get_setlist, which answer different queries.

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 makes clear that the tool applies when an artist's MusicBrainz ID is available, and it explains pagination via `p` for larger result sets. It does not explicitly contrast with search-based siblings or state when not to use this tool, so it falls just short of full exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it requires attribution as a clickable source link, specifies 'no nofollow', and gives a fallback URL when the result lacks a `url`. This is specific operational guidance an agent needs for correct presentation and goes beyond the structured 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 description is three sentences, front-loaded with the core operation ('Get a city by its geoId'), and every sentence carries distinct useful information: the identity key, the attribution requirement, and the fallback behavior. There is 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 read-only lookup with two parameters, the description plus the rich `view` parameter schema cover the essential calling and response-presentation details. It lacks explicit error case behavior or rate-limit warnings, but the attribution requirement and fallback URL address an important real-world nuance. No output schema exists, so the description's mention of the `url` field partially compensates.

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 baseline is 3. The description does not elaborate on the `view` parameter or add semantics to `geoId` beyond the schema's 'City's geoId'. It mentions the `url` field in results, but that is not parameter semantics. The schema already carries the parameter meaning.

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 verb and resource: 'Get a city by its geoId.' It also mentions the result includes a setlist.fm URL, giving agents a concrete idea of the return value. However, it does not explicitly differentiate this from sibling tools like setlist_search_cities, so it misses the 'distinguishes from siblings' bar for a 5.

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 phrase 'Get a city by its geoId' implicitly tells the agent to use this tool when a geoId is known and a city object is needed. Yet it provides no explicit when-not guidance or alternative routing (e.g., 'to search by name use setlist_search_cities'). Usage context is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnlyHint by explaining the response shape ('sets.set[]'), per-set encore/name metadata, and per-song flags ('tape', 'cover', 'with', 'info'), including the subtle caveat that 'tape: true' means not actually performed. It also prescribes attribution behavior for the returned URL with a fallback, which is non-obvious and valuable.

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 tool's core action and then packs only high-value information: response structure, song special cases, and attribution requirements. Every sentence earns its place with no redundant 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?

Since there is no output schema, the description carries the return-shape burden and satisfies it: it explains where songs live, how to interpret set and song metadata, and what to do with the returned URL. Combined with the annotations and well-documented parameters, an agent has enough to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents both 'setlistId' and 'view'. The description adds no parameter-specific meaning beyond what the schema provides, so it sits at the baseline score.

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 ('Get') and resource ('a setlist.fm setlist by its ID') plus what is included ('full song list and event details'), making it clear what this endpoint returns. This is distinct from the search and version-related sibling 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 phrase 'by its ID' implies the caller should already have a setlistId and signals this is a direct fetch rather than a search. However, it never explicitly names sibling alternatives such as setlist_search_setlists or setlist_get_setlist_version, nor does it state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses important attribution requirements: results include a setlist.fm url, and the agent must present it as a clickable source link with no nofollow. It also reveals a fallback behavior when url is missing (link to https://www.setlist.fm), which is the kind of non-obvious behavior an agent needs. It also explains field semantics like tape, cover, with, info, and encore.

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 substantial but every sentence adds necessary context: the wiki-edit concept, the data structure, and the attribution requirement. It could be slightly tighter, but it is logically organized and front-loads the tool's 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?

Given there is no output schema, the description carries the burden of explaining what the response looks like (sets, set[], songs, encore, name, tape, cover, with, info, url). For a GET tool with readOnlyHint and no destructive behavior, this is complete for an agent to call and interpret the result 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%, so the schema already documents both parameters. The description adds meaning to versionId by explaining where it comes from ('returned in a setlist's versionId field') and explains the response shape for view ('compact drops fields the response already carries elsewhere; full returns Setlist.fm's payload untouched'). This goes 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 states a specific verb ('Get') and resource ('a specific historical version of a setlist by its version ID'), which is distinct from siblings like setlist_get_setlist. It also explains the wiki-edit context that frames what a version is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly differentiates this tool from setlist_get_setlist by explaining that versionId comes from a setlist's versionId field, and it describes the data model enough to know when this version-specific lookup is needed. It does not explicitly name sibling alternatives or state 'use X instead', 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds useful behavioral context beyond the annotation by explaining the setlist.fm attribution requirement: present the returned url as a clickable source link, use followable attribution with no nofollow, and fall back to https://www.setlist.fm when no url exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the first sentence states the operation and key parameter, while the following sentences address attribution behavior. Every sentence carries necessary information, and there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with fully documented parameters and a readOnlyHint annotation, the description covers the essential operational details: what the tool returns (a profile with a url), how to attribute the result, and the fallback behavior when no url is present. It does not describe error cases or all return fields, but those are less critical given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both userId and view. The description adds only marginal clarification by equating userId with the username, which the schema already states. No additional parameter semantics are provided, so the baseline 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 states a specific verb ('Get'), a specific resource ('a setlist.fm user's public profile'), and the key identifier ('their setlist.fm username'). This clearly distinguishes it from sibling tools like setlist_get_user_attended and setlist_get_user_edited, which target different user-related data.

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 makes the usage context clear: call this tool when you need a user's public profile by username. It does not explicitly mention alternatives or exclusion criteria, but the resource is specific enough that an agent can infer when this tool applies versus the attended/edited list tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already signals this is a safe read operation. The description adds value beyond the annotation by disclosing the expected output data (results include a setlist.fm URL) and the required attribution behavior, including the nofollow policy and fallback URL. This is useful behavioral context not present in the schema or 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 with no wasted words: the first states the core purpose, the second gives pagination and URL citation guidance, and the third covers the fallback case. The most important operational instruction is 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 read-only tool with three fully documented parameters, the description covers everything an agent needs: what it returns, how pagination works, and how to present the results correctly. The read-only annotation covers safety, and the schema covers parameter details, leaving no critical 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces that 'p' controls pagination but adds no new field-level semantics beyond what the schema provides. Baseline 3 is appropriate when the schema carries the full parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Get the concerts a setlist.fm user has marked as attended.' This precisely distinguishes the tool from siblings like setlist_get_user_edited and setlist_mark_attended without needing to inspect schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear operational context: it explains pagination via the 'p' parameter and gives explicit presentation instructions for returned URLs. It does not explicitly name alternative tools or state when not to use it, but the attended-vs-edited distinction is strongly implied by the tool name and first sentence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only provide readOnlyHint=true. The description adds meaningful behavioral details: pagination via `p`, the presence of a `url` field, and a required attribution rule (followable clickable link, no nofollow) plus a fallback link when `url` is absent. This goes well beyond the annotations and helps the agent behave correctly when presenting results.

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 three sentences: first states the purpose, second covers pagination and the URL field, third gives the fallback and attribution requirement. Every sentence earns its place, and the most important information is 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 read-only, paginated list tool with a fully documented schema and readOnlyHint annotation, the description covers pagination, the presence of the url field, and the citation rule including an edge-case fallback. No output schema exists, but the description provides the most operationally critical return-field detail. It does not describe the full response envelope, but that gap is minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all three parameters (userId, p, view) with their meanings. The description only repeats that pagination is via `p`, adding no new parameter-level semantics. Baseline 3 applies because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get the setlists a setlist.fm user has created or edited.' This clearly distinguishes it from sibling tools like setlist_get_user_attended or setlist_get_artist_setlists by the 'created or edited' scope. No ambiguity remains about what resource this tool targets.

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 by identifying the resource ('a setlist.fm user has created or edited') and mentions pagination, but it does not explicitly contrast with alternatives such as setlist_get_user_attended. It provides clear context without exclusions or alternative routing, so it does not reach the level of explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, so the read-only safety profile is already covered. The description adds meaningful behavioral context beyond that: the attribution requirement (cite as a clickable source link with no nofollow) and the fallback behavior when a result has no URL. This is practical, non-obvious information that impacts how the agent should present output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the core purpose appears in the first sentence, and the following two sentences each carry distinct, necessary behavioral information about attribution. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only single-venue lookup with fully documented parameters, the description covers the key usage details: what the tool does and how to handle the URL in results. The lack of an output schema means a bit more detail about the returned venue structure could be helpful, but the two-parameter schema and readOnlyHint make this 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?

Schema description coverage is 100%, with both 'venueId' and 'view' fully described in the input schema, including enum details for 'view'. The description adds no extra parameter-level meaning beyond mentioning 'by its ID', so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a clear verb ('Get'), target resource ('a setlist.fm venue'), and lookup key ('by its ID'). It distinguishes from sibling search tools by emphasizing direct ID lookup, though it does not explicitly name any sibling or contrast with setlist_search_venues or setlist_get_venue_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?

No guidance is given about when to use this tool versus alternatives. An agent must infer from the tool name and sibling list that this is for a single venue lookup rather than searching venues or fetching venue setlists. There is no explicit when-to-use or when-not-to-use statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true, which is consistent. The description adds valuable behavioral context beyond the annotation: pagination via `p`, the requirement to cite results as clickable source links to setlist.fm per API terms, and fallback linking when no URL is present. This gives the agent clear operational guidance.

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 the core purpose, followed by pagination and attribution instructions. No wasted words; every sentence 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 tool with 3 params (1 required) and no output schema, the description covers the essential call context, pagination behavior, and critical attribution rules. It does not describe the full response structure, but that is partially implied by 'setlists' and the explicit mention of the URL field. The gap is minor given the simplicity of the operation.

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 all parameters. The description reinforces pagination via `p` but adds only marginal extra meaning (e.g., that page 1 is default, which the schema states). It does not add novel parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get setlists performed at a venue') and the resource (venue) with identifier type, which clearly distinguishes it from sibling tools like setlist_get_artist_setlists or setlist_get_venue. It also specifies ordering (most recent first).

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 gives clear context (venue ID, pagination, ordering) but does not explicitly mention alternatives or when not to use this tool. Usage is implied (when you have a venue ID and want its setlists) but no exclusions or alternative routing are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds genuine value beyond these: the specific endpoint called, the return shape {ok, authenticated, country_count}, and the plain-English hint distinguishing 'no key' vs 'bad key' vs 'API error'. The trailing 'Read-only.' repeats the annotation and adds no new information, but the rest is substantive.

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 tight sentences that front-load the verb and resource, with the return format and failure modes in the second sentence. The only waste is the trailing 'Read-only.', which duplicates the readOnlyHint annotation and could be dropped.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema and strong annotations, this description is complete: it covers purpose, the exact mechanism, the return values, failure-mode disambiguation, and safety. Nothing an agent needs to invoke 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?

The tool has zero parameters, so the baseline is 4 and the description has no parameter burden to carry. It appropriately explains the internal mechanism (calling the countries endpoint) without needing to document any inputs.

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 ('Confirm'), a specific resource ('setlist.fm countries endpoint'), and the outcome being verified ('API key is configured and works'). The purpose is unambiguous and clearly distinct from all 21 sibling tools, none of which perform health checks.

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 title 'Verify setlist.fm API key + connectivity' provides clear context for when to use this tool, and the description reinforces that it is a diagnostic/verification tool rather than a data-query tool. However, it never explicitly names alternatives or states exclusion conditions (e.g., 'use before other setlist calls'), leaving the when-to-use guidance implicit rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context: 'Pure local parsing — no network call' and 'Errors if no ID can be parsed'. It also details input tolerance (http/https, www, trailing slash, etc.) and scoping constraints, enriching the behavioral profile beyond the structured fields.

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 five sentences, each serving a purpose: purpose, output, scope, tolerances, and error handling. It is front-loaded with the primary function and contains no fluff or redundant phrases.

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, the description fully covers what it does, when to use it, what it returns, input constraints, and failure modes. It names downstream tools and explicitly states it's a local operation, leaving no critical gaps for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the schema already describes the url parameter well, but the description adds semantics about accepted URL forms, rejected page types, and error behavior. This goes beyond the schema example, giving the agent a richer understanding of the parameter's constraints.

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 'Parse' and the resource 'setlist ID out of a setlist.fm setlist URL', and explicitly distinguishes this utility from sibling tools by focusing on URL-to-ID extraction. It also mentions the output format and downstream use, making the tool's role unambiguous.

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 this tool ('paste a link instead of hunting for the ID') and names the downstream tools it feeds into. It also explicitly states exclusions (artist and venue URLs are rejected), which clarifies when not to use it, though it doesn't explicitly list alternative tools for those cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Going beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true), the description discloses meaningful behaviors: authentication via session cookie, dry-run returning a preview and making NO change without confirm: true, verification by re-reading the attended list after confirming, and the API-term attribution rule (followable link, no nofollow) with a fallback URL. 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?

Purpose is front-loaded, and each subsequent sentence carries distinct, necessary information: auth, idempotency, confirm/dry-run semantics, and attribution obligations. The density is justified for a mutation tool with this many constraints; there is 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 mutation tool with no output schema, the description covers the essentials: auth requirement, dry-run vs. confirm behavior, verification step, and how to handle the url in results. The only minor gap is that the full result shape beyond url is not described, which an agent might need for robust success/failure checks.

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 confirm and setlistId with adequate descriptions. The tool description marginally reinforces confirm as a safety switch and hints that setlistId originates from setlist_search_setlists / resolve_concerts, but adds little beyond the schema. Baseline 3 applies for high coverage.

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 uses a specific verb and resource: 'Record on YOUR setlist.fm account that you attended a show — the site's "I was there" marker — by setlist ID.' It clearly scopes the action to the user's own account and keys it by setlist ID, which distinguishes it from read-only siblings like setlist_get_setlist and from the reverse operation setlist_unmark_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?

The description gives clear usage context: it is the tool for marking attendance on the user's account, requires the SETLIST_SESSION_COOKIE as an explicit prerequisite, and explains the confirm-gated dry-run flow. It stops short of a 5 because it never explicitly names alternatives (e.g., 'to remove the marker, use setlist_unmark_attended'), but the guidance is unambiguous and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even though readOnlyHint=true already signals safety, the description discloses substantial behavior beyond the annotation: ~2 req/sec pacing, pending:true handling, the relevance-lookup and punctuation-normalization fallback chain, tourReference semantics, hasSongs:false stub flags, and the attribution/citation requirement. This is far richer than the structured annotation alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Core purpose, input shape, and return format are front-loaded in the first sentences, and nearly every later sentence earns its place (pacing, fallbacks, attribution). It is long, and 'Keep batches ≤24' mildly duplicates the schema's maxItems, but the density is justified for a multi-path batch tool.

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 explaining return values — and it does, naming every returned field and summary counter. All non-obvious behaviors (pending on time budget, tourReference labeling, no-nofollow citation rule) are covered, leaving an agent with enough 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: how artist+date anchor the search, city/venue narrowing the match, the ≤24 batching constraint tied to rate limiting, and the default true for tourFallback with its cost implication (extra lookups). These details go well beyond the schema's field-level 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 states a specific verb+resource ('Resolve many concerts to their setlists in ONE call') and immediately contrasts it with the per-show alternative, making it clearly distinct from single-lookup siblings like setlist_get_setlist or setlist_search_setlists. The return shape and summary counters further pin down exactly what the tool produces.

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 clear context: use when resolving multiple concerts at once ('instead of 2+ per show'), keep batches ≤24, and re-call with pending items rather than timing out. It also instructs how to opt out of tour-reference lookups via tourFallback: false, though it never names a specific sibling tool for when a single lookup is the better choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral detail beyond the schema: results include a setlist.fm URL, presentation must cite it as a followable source link (no nofollow), and fallback URL when the result lacks one. This is meaningful operational context an agent needs.

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 the essential mbid-linkage and attribution requirements. Each sentence earns its place: the first states the operation, the second connects to sibling tools, and the third gives a citation rule that affects agent behavior. 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?

For a read-only search tool with fully documented parameters, the description covers the main invocation flow: search by name/mbid, receive mbid/url, and use the mbid downstream. It also covers the attribution edge case (missing url). It does not describe result pagination or formatting details, but the schema already documents the page parameter and no output schema exists. This is effectively complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with all five parameters described in the input schema itself. The description reinforces that search is by 'name or MusicBrainz ID,' mapping to artistName and artistMbid, but it does not add meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the parameter documentation load.

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 uses a specific verb and resource: 'Search setlist.fm for artists by name or MusicBrainz ID.' It clearly distinguishes itself from sibling tools by stating it returns matching artists with their mbid shape the caller needs for follow-up artist or setlist retrieval. This is a focused, unambiguous purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context: use this when you need to find artists and then get their mbid for further artist or setlist calls. It names downstream tools but does not explicitly state when to prefer this over alternatives like setlist_search_setlists or setlist_get_artist. The guidance is clear enough for inference but not explicit about exclusion scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses important behavioral requirements: results include a setlist.fm URL, attribution must be clickable and followable, and results without a URL should link to https://www.setlist.fm. This is genuinely useful operational context not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core action, then provides downstream usage, then attribution requirements. Each sentence contributes distinct value with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is largely complete for an agent: it states the search behavior, the key return value (geoId), how to use that value, and citation requirements. A small gap is that it does not clarify whether at least one search parameter should be provided, even though the schema lists zero required parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all six parameters with full coverage, so the tool description does not need to restate them. The phrase 'by name and/or location' loosely maps to name/state/country/stateCode, but the description adds little beyond the schema's per-parameter 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 opens with a specific verb and resource: 'Search setlist.fm for cities by name and/or location.' It clearly explains what the tool returns ('cities with their geoId') and how that output relates to sibling tools, so an agent can distinguish it from venue, artist, and setlist 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 gives practical usage context by explaining that the returned geoId should be used as cityId in setlist_search_setlists, setlist_search_venues, or setlist_get_city. It does not explicitly contrast this tool with sibling search tools like setlist_search_venues, but the downstream usage guidance makes the intended role clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses an important behavioral requirement: results must be presented as clickable setlist.fm source links because API terms require followable attribution, with a fallback to https://www.setlist.fm when no url exists. This is useful operational context not visible in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose and output, downstream usage, and attribution requirements. The information is front-loaded with the core listing behavior before moving to usage and presentation rules. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with no required parameters and no output schema, the description covers the essential return content (countries, ISO codes, URLs) and the key follow-up action. It could be more explicit about the exact response container or pagination, but for 'list all countries' the guidance 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?

The single `view` parameter is already fully documented in the schema, including compact/full behavior and the explicit no-field-projection caveat. The tool description does not add parameter-level detail, so the baseline of 3 for high schema coverage 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 specific verb and resource: 'List all countries supported by setlist.fm, with their ISO country codes.' This clearly differentiates the tool from siblings like setlist_search_cities or setlist_get_venue, and the mention of ISO codes adds concrete output expectations.

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 gives clear downstream context: 'Use a code as countryCode in setlist_search_setlists.' This tells an agent why and how to apply the result. It does not explicitly name alternatives or exclusions, but the usage context is strong enough for the intended workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations carry only readOnlyHint=true, and the description adds substantial behavioral context on top: the at-least-one-filter constraint (which contradicts the schema's required:0, so it is essential), the multi-city span behavior, the API-terms attribution requirement ('followable attribution — no nofollow'), and the fallback to https://www.setlist.fm when no url is present. These are operational traits annotations cannot express.

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?

All seven sentences earn their place: purpose, filter rule, disambiguation, alternative pattern, stub-setlist detection, attribution, and URL fallback — with the purpose front-loaded in sentence one. The weakness is structural: everything runs as a single dense paragraph with em-dash asides, which is harder for an agent to scan than a short bulleted breakdown would be.

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 15-param tool with no output schema, the description covers the decision-critical response fields (songCount, setCount, hasSongs, url) and the attribution behavior. But pagination is undocumented: the p parameter exists in the schema while the description never states page size, how to detect the last page, or how results are wrapped in the response, so an agent paging through results would be guessing.

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, and the description pushes beyond it by explaining how parameters combine: artistName + date needs a city/venue qualifier to pin the exact show, and omitting the artist with venueName/venueId + date returns every performer at a venue. It states the at-least-one constraint that the schema cannot, since all 15 params are individually optional. It adds nothing on p, view, or lastUpdated, but those are already well described in 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 opening sentence 'Search setlist.fm for concert setlists' names a specific verb and resource in one line. The description also documents a second distinct usage mode ('list EVERY performer at a venue or festival that day'), which sets it apart from sibling search tools (search_artists, search_venues) and lookup tools (get_setlist, get_artist_setlists) without the agent having to open their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit in-tool guidance: the at-least-one-filter rule, a concrete disambiguation strategy ('artistName + date can span multiple cities, so add cityName/cityId or venueName/venueId'), and an alternative invocation pattern for venue-based browsing. However, it never names sibling tools for the when-not cases (e.g., get_setlist for a known ID, get_artist_setlists for a known artist), so exclusion routing is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses an important behavioral requirement: attribution must be followable (no nofollow) per setlist.fm API terms, and provides a fallback URL if none is present. This adds operational context not captured by the annotation. It does not cover rate limits or error behavior, but for a read-only search tool the attribution detail is a notable addition.

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 composed of two sentences: the first defines the core function and usage, the second details attribution requirements. It is front-loaded with the primary purpose and avoids redundancy. The attribution guidance, while specific, is essential for compliance and does not bloat the text unnecessarily. Slightly verbose but well-organized.

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 search tool with no output schema, the description covers the essential aspects: what it searches, what it returns (venue ID and URL), and how to use the results (with get_venue tools). The attribution fallback is also covered. Pagination is implicit via the 'p' parameter in the schema. The description is sufficient for an agent to call this tool correctly without additional clarification.

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 input schema already provides 100% coverage with descriptive comments for all eight parameters, so the baseline is 3. The description only mentions 'name and/or location' which loosely maps to the name, city, state, country fields, but adds no new semantic details beyond what the schema states. It does not clarify relationships between parameters like state vs. stateCode, but that is also documented in 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 action ('Search setlist.fm for venues') with a specific resource and distinguishing scope ('by name and/or location'). It also references related tools (setlist_get_venue, setlist_get_venue_setlists) which differentiates it from sibling search tools like setlist_search_artists or setlist_search_cities. The mention of returning venue IDs makes the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by indicating that this search is a precursor to retrieving venue details or setlists ('use it with setlist_get_venue or setlist_get_venue_setlists'). It does not explicitly list exclusions (e.g., when to use search_cities instead), but the phrase 'for venues' inherently communicates its domain. The guidance is adequate for an agent to select this tool appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite annotations already indicating destructive and idempotent behavior, the description adds substantial value: dry-run preview without confirm, actual removal with confirm, verification by re-reading, no-op behavior when not attended, and attribution requirements for returned URLs. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every clause earns its place: purpose, reversal relationship, authentication, idempotence, dry-run mechanics, verification, and URL attribution. It is front-loaded with the primary action, though the long final sentence could be split for readability.

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 mutating tool with no output schema, the description is complete: it covers authentication, destructive behavior, idempotence, dry-run execution, confirmation semantics, verification, and how to attribute results. An agent has all the information needed to invoke this tool safely and 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%, and both parameters are already documented in the schema. The description restates the confirm behavior and setlistId purpose but does not add significant new parameter-level detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('Remove a show'), a specific resource ('YOUR attended list on setlist.fm'), and the identifying input ('by setlist ID'). It also explicitly frames the operation as the reverse of setlist_mark_attended, which differentiates it from its sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it requires an authenticated session, is idempotent, and behaves differently with or without confirm:true. It names setlist_mark_attended as the reversed operation, giving the agent a direct alternative reference, though it does not enumerate when-not-to-use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.