setlist_resolve_concerts

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.