LONG Events

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds data-quality details (nullable mbid, verified spotify_id) and the ability to supply one of three identifiers, which is useful. However, it does not disclose any potential limitations, such as response size, rate limits, or failure modes. It adds some context beyond annotations but not extensive behavioral insight.

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 concise sentences with no wasted words. It front-loads the core purpose, then specifies the parameter options, and ends with illustrative use cases. Each sentence contributes distinct value, and the structure is easy to scan.

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 tool with three optional parameters and no output schema, the description covers the main action, the acceptable identifiers, and when to use it. It also lists the response content (profile, mbid, spotify_id, dates, history). It doesn't mention error handling or edge cases, but given the simplicity and annotation coverage, it is sufficiently complete for an agent to call 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% for each parameter, so the baseline is 3. The description adds the crucial insight that artist_id, slug, or name are interchangeable alternatives ('Provide artist_id, slug, or name'), which is not explicitly stated in the schema. This clarifies that any one of them is sufficient, adding meaning beyond the individual 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 clearly states the action: 'Get one artist's profile' and lists specific data fields (nullable mbid, verified spotify_id, upcoming dates, recent history). It includes example queries ('Tell me about Tale of Us') that ground the purpose. It distinguishes from siblings by focusing on a single artist's profile rather than events or listings, though it doesn't explicitly name alternatives.

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 concrete usage examples ('Use this to answer...') that illustrate when to invoke it. It implies the tool is for retrieving artist profile information, but does not explicitly state when not to use it or mention alternative tools like get_artist_events. The guidance is clear but lacks explicit exclusion or routing to siblings.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful details beyond annotations: artist identity includes nullable mbid and verified spotify_id, and performances carry ticket_url as the resolved closest-to-purchase link. It doesn't cover return-shape details like total counts, but the annotations carry the 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?

The description is three sentences, front-loaded with purpose and followed by a use case and return-value detail. It is efficient overall, though phrases like 'stable identity' are slightly abstract and could be clearer.

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

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

With 10 parameters, 0 required, and three alternative artist identifiers (artist_id, name, slug), the description does not clarify which identifier takes precedence or whether they are alternatives. It also doesn't mention pagination limits beyond the schema. It is adequate but leaves an important invocation ambiguity unaddressed.

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 every parameter is documented in the input schema. The description implies filtering by city/country/date through its example but adds no new syntax or semantics beyond what the schema provides. Baseline 3 is appropriate when 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 uses a specific verb ('List') and resource ('one artist's stable identity and performances'), making the scope clear. It implicitly distinguishes itself from search_events and search_artists by focusing on a single artist's full schedule, but doesn't name alternatives explicitly.

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 a concrete example use case ('Where is Peggy Gou playing in Europe next month?') and mentions paging through a touring artist's full schedule. It gives clear context for when to use the tool, but lacks explicit exclusions or named alternatives.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context about output content (statistics, recent activity) without contradicting 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 two sentences, front-loaded with the action, and contains no redundant 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?

The tool is simple with optional parameters and rich annotations, but there is no output schema. The description gives a hint about returned statistics but does not specify the exact response structure, which an agent might need to parse results correctly. Slightly incomplete.

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% for all three parameters, so the schema fully documents them. The description does not add any parameter-specific detail, so 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 the verb 'list' and the resource 'cities', and adds the unique aspect of statistics like total events and recent activity. It does not explicitly differentiate from sibling tools like get_event_week_cities, but the purpose is clear and not tautological.

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 a usage context ('Use this to help users discover active event scenes') but does not mention when to avoid this tool or name alternatives. The 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.

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the lower bar applies. The description adds genuine behavioral value beyond those hints: the description is 'untruncated', the end time is 'predicted' only 'when the listing omitted one', and the ticket offer is 'publishable' — traits inferable from neither annotations nor schema.

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?

A single front-loaded sentence that opens with the action and then packs the value-adding return inventory into a compact list. Every clause earns its place; there is no filler and no repetition of schema or annotation 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 single-parameter, read-only, idempotent tool, everything needed to invoke it correctly is present: the parameter is fully documented in the schema, safety is carried by annotations, and the absence of an output schema is compensated by the detailed enumeration of return fields, including the conditional 'predicted end time' behavior.

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 schema already defines event_id as 'The UUID of the event to retrieve'. The description's 'by its ID' reiterates that role without adding format, constraint, or usage nuance, so the high-coverage baseline of 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?

States a specific action ('Get full details') against a specific resource ('a specific event') with a clear accessor ('by its ID'), then enumerates the exact return contents. This distinguishes it from sibling search/list tools like search_events and get_event_schedule, whose names imply broader query scopes rather than point 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 'by its ID' phrasing clearly signals the tool requires a known event UUID rather than a query, which orients an agent to choose it only when an identifier is already in hand. It does not, however, explicitly name alternatives or exclusion conditions, a minor gap given 16 siblings.

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 cover read-only/idempotent/non-destructive behavior. The description adds useful output behavior by stating that it returns set times, stages, and artists, which is especially important since there is no output schema; it also gives example queries that imply name-based lookup. It does not discuss edge cases like empty results or filter combination semantics, but no annotation contradiction 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?

Two front-loaded sentences: the core action and return content come first, followed by two illustrative questions. There is no filler or redundant restatement of the title/schema.

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

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

For a read-only lookup tool with four optional filters and no output schema, the description covers purpose, return values, and typical usage. A small gap is the lack of guidance on event_id vs event_name precedence or how stage/artist filters combine, but these are optional refinements and the examples make the common cases unambiguous.

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?

All four parameters have schema descriptions (100% coverage), so the baseline is met. The description's example questions enrich the semantics by mapping natural-language requests to artist and event_name, which helps the agent see how to populate those fields; stage is left to 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 opens with a specific verb and resource ('Get the DJ/artist schedule'), then enumerates the returned content ('set times, stages, and artists'). This clearly differentiates it from siblings like get_event_details and get_now_playing by focusing on schedule/lineup rather than general event or current-play info.

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 'Use this to answer questions like...' sentence gives concrete query patterns that signal when the tool is appropriate. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full routing 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 already establish the tool as read-only, idempotent, non-destructive, and open-world. The description adds useful output context ('cities' and 'counts') but does not disclose details such as how 'upcoming' is defined, count semantics, sorting, or pagination behavior.

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 no filler. The first sentence front-loads the core operation and output; the second sentence adds practical purpose without 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?

For a zero-parameter, read-only tool with no output schema, the description is complete enough to invoke: it names the output entity, the count detail, and the use case. Nothing essential for calling the tool 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 input schema has no parameters, so the baseline is 4. The description adds relevant response context by explaining the tool returns cities with associated counts, which is sufficient for a zero-parameter tool.

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 operation and resource: 'List cities that have upcoming event weeks with their counts.' This clearly distinguishes the tool from siblings like get_cities, get_event_weeks, and get_event_week_details by identifying exactly what is returned.

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 a concrete use case: 'Use this to discover where major conferences are happening.' This provides clear context for when the tool is relevant, though it does not name alternatives or explicitly state 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds one real behavioral fact — the 100 side-event cap — which tells the agent the result is bounded. It says nothing about what happens when no identifier is supplied, nor about truncation or ordering of those 100 events.

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 short sentences with the capability stated first and the usage hint second; nothing is padded. The second sentence is slightly vague ("bounded discovery") but still earns its place as a scope cue.

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 need not explain return values since there is no output schema, and annotations cover the safety profile. The bounded 100-event behavior is disclosed, and the identifier parameters are fully documented in the schema, so nothing essential is missing 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%, so slug, week_id, and the event_week_id alias are already documented in the schema, making a 3 the baseline. The description does not clarify the precedence between the three equivalent identifiers or whether one is required, which is the main ambiguity the schema leaves open.

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 gives a specific verb and resource ("Get details for a conference week") plus a distinctive payload fact ("up to 100 side events"), which separates it from get_event_details (a single event) and get_event_weeks (a list). It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

"Use this for bounded discovery during a major conference" implies a context but gives no explicit when-not condition and no pointer to alternatives such as get_event_week_cities, get_event_week_tags, or get_event_schedule. An agent must guess whether this tool or a sibling is the right entry point.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful context that results are 'upcoming' and include multi-day event series, but does not disclose additional behaviors like sorting, pagination, or whether summaries vs. full details are returned.

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 compact sentences with no filler: the first front-loads the action and resource, the second gives the use case. The examples are high-value 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?

For a simple read-only list tool with five optional parameters fully documented in the schema, the description is largely complete: it names the resource, scope, and use case. The only noticeable gap is not pointing to search_event_weeks or get_event_week_details when a more targeted query or deeper detail is needed, but this is minor given the low 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 description coverage is 100%, so the schema fully documents all five parameters. The description adds no parameter-specific meaning beyond what the schema already provides, 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 uses a specific verb ('List') and names the exact resource: upcoming conference weeks, festivals, and multi-day event series, with concrete examples (ETH Denver, Devconnect, Token2049). This clearly differentiates it from search-oriented siblings like search_event_weeks or detail tools like get_event_week_details.

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

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

It explicitly states the intended use case: helping users plan trips around major conferences. However, it does not name alternatives or state when NOT to use this tool, such as when the user needs a free-text search for a specific event week name.

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 cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds value by disclosing that the result is an aggregated list of tags with counts. 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?

Two compact sentences with no filler. The first sentence states the operation and result; the second explains the intended use case. Both sentences earn their 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 zero-argument, read-only listing tool, everything needed to invoke it correctly is present. The description clearly states what the response will contain (tags and counts), so the absence of an output schema is not a gap.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meaning because the input schema is empty.

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 ('List') and resource ('all tags used in event weeks'), and clarifies the output shape ('with their counts'). The use-case phrase 'discover types of conferences available' differentiates it from sibling tools that return event-week records.

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 tells the agent when to use it: to discover types of conferences available. It does not name alternative tools or exclusion cases, so it falls just short of full 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 already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the 'live stage information' return concept and current-time semantics, but does not explain timezone handling, how 'now' is determined, or what happens when nothing is playing. That is acceptable for a read-only tool but not especially rich.

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: it states the core purpose first, then the return value, then example queries. Every sentence earns its place and there is no redundant restating of the tool name or schema.

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

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

For a simple read-only lookup with three optional filters and full schema coverage, the description and schema together give an agent enough to select and call the tool correctly. The return value is summarized, and there is no output schema to explain. A slightly deeper note on default scope when no filters are given would be the only meaningful gap.

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

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

Schema description coverage is 100%, with each parameter described as a filter (city, event_id, event_week_id), so the schema carries the parameter documentation burden. The description does not add meaning beyond the schema, which puts it at the baseline of 3.

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 ('Get') and a clear resource ('what's currently playing at festival/party events'), and immediately clarifies the return value: 'live stage information with current artists.' The 'now' emphasis cleanly distinguishes it from schedule-oriented siblings like get_event_schedule or get_event_details.

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 explicit natural-language use cases: 'What's on now?' and 'Who's playing right now at AYA?' This tells the agent when to reach for this tool. However, it does not explicitly say when not to use it or mention alternatives such as get_event_schedule for future lineups, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the safe read-only profile. The description adds one behavioral detail beyond annotations: results include event history. It does not disclose sorting, pagination, or how 'popular' is determined, so a middle score is appropriate.

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 short sentences, front-loaded with the action and resource. The first sentence states the core behavior, the second justifies when it is useful; neither sentence is 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 list operation with two fully documented parameters and safety annotations, the description is nearly complete: it covers city scope, the event-history detail, and the use case. It omits output format specifics, but no output schema exists and the tool is simple enough that this is only a minor gap.

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

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

The input schema documents both parameters with 100% coverage, including the default of 20 for limit. The description adds no extra parameter semantics beyond restating the city scope, which the schema already handles. Baseline 3 applies.

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

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

The description states a specific verb ('List'), a resource ('venues'), and a scope ('in a city'), adding a distinguishing detail ('with their event history'). It also frames the intended user value (finding popular venues or discovering new spots), which clearly separates it from the artist/event/city 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 sentence 'Use this to help users find popular venues or discover new spots' gives explicit when-to-use context. It does not mention alternatives or exclusions, but no sibling tool targets venues, so this guidance is sufficient without needing a when-not clause.

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 the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context: ordering by tracked performances, optional scoping by city/country, and data-quality caveats about nullable mbid and verified spotify_id fields. 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?

Two sentences with no wasted words: the first front-loads what the tool returns and how results are ordered, and the second gives concrete query examples. 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?

Given 8 optional parameters but no output schema, the description covers the main intents with examples and scoping semantics. It lacks explicit return-format detail beyond the field caveats, but the schema and annotations carry most of the remaining burden.

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?

All 8 parameters are documented in the input schema, so the baseline is 3. The description reinforces the meaning of city/country filters and the 'performances we track' ordering related to min_events, but it does not add 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 uses a specific verb ('Browse') and resource ('artists'), and adds distinguishing details: optional city/country scoping and ordering by tracked performances. It does not explicitly contrast with the sibling search_artists, so it misses the full sibling-differentiation bar.

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 'Use this to answer...' and provides two representative use cases covering location-based queries and tour-frequency ranking. It gives clear context for when to use the tool, though it does not name alternatives or state 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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: results are bounded ('up to 100 entries per collection'), and artist records carry nullable mbid and cross-provider-verified spotify_id, which tells the agent to expect missing identifiers and to trust spotify_id for matching.

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, but the three example questions repeat the same idea and read as marketing filler, and the '100 entries per collection' bound duplicates the schema's limit description. The one high-value sentence is the mbid/spotify_id note, which is buried in the middle.

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

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

With seven parameters, no output schema and no nested objects, the description should more fully explain the return shape; 'bounded selection of tracked performances ... per collection' is ambiguous about whether collections are artists or performances, and it says nothing about truncation, pagination, or empty-result behavior. It is adequate for calling the tool but leaves return-value expectations partly unclear.

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 all seven parameters are already documented, establishing a baseline of 3. The description adds only a loose hint that city/country filtering exists ('Which cities is Nina Kraviz touring?') and restates the 100-entry bound already in the limit parameter, adding little semantic detail 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?

States a specific verb and resource ('Search artists by name') plus the payload ('a bounded selection of tracked performances'), which is more than a restatement of the name. It does not distinguish itself from siblings like list_artists or get_artist, so an agent cannot tell from the description alone which one to pick for lookups vs. listing.

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 with 'Use this to find when and where a specific artist is playing' and three concrete example questions that map well to likely user phrasing. There are no exclusions or named alternatives (e.g., when to prefer get_artist or list_artists), which keeps it below a 5.

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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description correctly spends its space on behavior the agent cannot see elsewhere: the provenance of the `description` field, the meaning and ordering of `lineup`, the 0-100 `rank`, and the conditions under which `predicted_end_time` and `ticket_offer` appear. It does not discuss result ordering, result volume, or pagination semantics beyond the cursor parameter, which keeps it from a 5.

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

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

Purpose is front-loaded in the first sentence and the return-value semantics follow in a compact block that is dense but all substantive. The parenthetical enumeration of summary inputs (venue, local date and time, category, organizer, lineup) is the only slightly padded phrase, but it earns its place by explaining what a generated description contains.

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

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

With ten optional parameters, no required parameters, and no output schema, the description carries the burden of explaining returns and does so thoroughly, covering the synthesized description, lineup ordering, rank, predicted end time, and ticket offers. The remaining gap is behavior with no location argument supplied and how results are ordered or paginated across calls, which the description never addresses.

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 all ten parameters, including defaults for limit and radius_km and the ISO date formats, are already documented in structured data; the baseline of 3 applies. The description only restates that filters are optional and that search is by city or coordinates, without clarifying whether city and lat/long can be combined or which wins when both are supplied.

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 gives a specific verb and resource ('Search for events') and scopes it to a location plus optional filters, which cleanly separates it from artist- and week-oriented siblings like get_artist_events or search_event_weeks. It stops short of explicitly naming a sibling it is not, so an agent must infer the boundary rather than being told.

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

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

'Use this to help users find events in a city or near coordinates' gives a positive usage cue for the two location modes. There is no when-not guidance and no mention of when to prefer search_event_weeks or get_artist_events, so the routing decision against siblings is left implicit.

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 annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the matching behavior (matches against name, description, or city), which is useful but does not describe result shape, ordering, or pagination. With the annotation safety profile established, this is adequate but not rich.

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 short sentences with no filler. The primary action and scope are front-loaded, and the use-case guidance is efficiently delivered in the second sentence.

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 search tool with two fully documented parameters and rich annotations, the description is nearly complete. It does not explain result format, but with no output schema and the tool's straightforward nature, this is a minor gap rather than a functional one.

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 both parameters are already fully documented in the schema. The description's mention of 'name, description, or city' clarifies what the query matches but does not add new parameter-level detail 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 ('Search'), a clear resource ('event weeks'), and the searchable fields ('name, description, or city'). It further clarifies the tool's intended use case ('find specific conferences or festivals'), which distinguishes it from listing-oriented siblings like get_event_weeks.

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 'Use this to find specific conferences or festivals' provides clear context on when to invoke this tool. It does not explicitly name alternatives or exclusions, but it gives enough guidance for an agent to select it for targeted searches.

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