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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context: pagination (returns paginated results) and the output shape (artist, venue, date, tracks). The date-format warning in the schema's 'date' param also adds behavioral detail, though that lives in the schema rather than description. The description contributes pagination and result-shape info beyond what annotations provide.

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

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

The description is a single efficient sentence that front-loads the purpose. No wasted words. It logically lists search criteria and the result shape. It could arguably add usage guidance but the sentence is appropriately concise for its 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?

The tool is moderately complex (13 parameters, all optional, with ambiguous field relationships like cityId vs cityName and artistMbid vs artistName). The description adds the result shape and pagination, but given the 8% schema coverage and many sibling search tools, it leaves meaningful gaps: no guidance on which parameter combination to prefer, no explanation of MBID vs name lookups, and no format notes for year/state/country. It's adequate but not complete for a tool with this parameter surface.

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 only 8% (only the 'date' param has a description). With 13 parameters and nearly zero schema descriptions, the description must compensate, but it only lists the search fields by name without explaining their formats, semantics, or interactions (e.g., how artistName relates to artistMbid, or what cityName vs cityId mean for lookup). The only meaningful parameter detail (date format warning) lives in the schema, not the description. For a 13-param tool at 8% coverage, this is a significant gap.

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 (search) plus resource (setlist.fm setlists) and enumerates the search fields (artist name/MBID, date, year, city, country, state, tour, venue). Purpose is clear. It doesn't explicitly distinguish from sibling tools like setlist, artist_setlists, or venue_setlists, but 'setlist_search' is distinct enough by name, and the description accurately maps to that broad-search scope.

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 this is the general search entry point (searching by many criteria), which contrasts with siblings like artist_setlists and venue_setlists that search by a single entity. However, it never explicitly states when this tool should be used versus those alternatives, nor when NOT to use it. The contextual guidance 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.