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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral detail: the artist record includes nullable mbid and verified spotify_id, and each performance carries a ticket_url resolved to the closest-to-purchase link. This helps set expectations for the returned data.

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 tight sentences: the first defines scope, the second gives concrete usage examples, and the third clarifies a key return field. Every sentence earns its place with no redundant material.

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

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

The description covers main return fields and a realistic use case, but it leaves a meaningful gap: 0 parameters are required while the tool promises 'one artist', so an agent may be unsure whether name, slug, or artist_id must be supplied. With no output schema, this ambiguity is not resolved elsewhere.

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 parameters are already well documented. The description adds no extra parameter semantics, such as which identifier is preferred or how filters combine, so it stays at the baseline 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 names a specific verb and resource: 'List one artist's stable identity and performances with filtering and pagination.' It also gives a concrete example query. However, it does not explicitly differentiate this tool from siblings like search_events or get_artist, though the 'one artist's' scope is a good implicit cue.

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 use cases: answering 'Where is Peggy Gou playing in Europe next month?' and paging through a touring artist's full schedule. This tells an agent when to use the tool, but it does not mention exclusions or when to prefer an alternative such as search_events.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scope detail that the response includes all side events, but it does not disclose additional behavioral traits such as return format, pagination, or auth requirements.

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

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

Two short sentences with no filler. The first sentence defines the operation and scope, and the second provides usage context. Every word 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 read-only tool with rich annotations and self-documenting parameters, the description is sufficient: it identifies the resource, the retrieval action, and the inclusive scope of side events. It could be more explicit about the returned fields, but the absence of an output schema is partially mitigated by 'full details'.

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 slug, week_id, and event_week_id. The description adds no parameter-level guidance, which keeps this at the baseline rather than above it.

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 action ('Get full details') and a specific resource ('a conference week'), and adds a distinguishing scope ('including all its side events'). This clearly separates it from siblings like get_event_weeks or get_event_week_cities without needing to open the schema.

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 see everything happening during a major conference' gives clear intent and a concrete user-facing scenario. It does not explicitly list alternatives or when-not-to-use, but the context is strong enough for an agent to select it 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?

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context about data provenance ('across all sources') and field semantics ('nullable mbid and cross-provider-verified spotify_id'), but it also claims 'every performance we know about' without acknowledging the default upcoming_only=true filter, which could mislead an agent into thinking all historical performances are returned. This is a notable gap.

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: the first states the action and scope, the second adds stable-matching fields relevant for agent decision-making, and the third gives concrete usage examples. Information is front-loaded, with 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 tool without an output schema, the description should clarify the return shape. It mentions artist records with mbid and spotify_id and implies the output answers when/where questions, but it does not explicitly state that results include embedded performance details (dates, venues, cities) or how to control pagination and default filters. Given the tool's 7 parameters and no output schema, this is a moderate gap that the description only partially fills.

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 every parameter is already documented. The description adds no parameter-specific semantics beyond implying that artist_name is the core search term through examples. It does not elaborate on date formats, filter combinations, or the effect of upcoming_only, so it does not exceed 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?

Description clearly states a specific verb and resource: 'Search artists by name and get every performance we know about, across all sources.' It distinguishes itself from siblings like list_artists (which presumably lists all artists) and get_artist (which returns a single artist) by emphasizing name-based search with performance results. The example questions ('When does Bonobo play?') reinforce this exact 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 explicitly says 'Use this to find when and where a specific artist is playing' and provides three example queries, giving clear context for when to invoke this tool. However, it does not explicitly mention alternatives or when not to use it (e.g., 'for a known artist ID, use get_artist'), so it stops short of a full 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 this read-only and non-destructive, and the description goes further by disclosing conditional output behavior: generated-vs-organizer descriptions, predicted_end_time only when needed, ticket_offer only when fresh, and rank semantics. This substantially helps an agent interpret responses.

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 purpose is front-loaded and every sentence carries information: location scope, optional filters, output-field caveats, and the city/coordinates usage note. The detail is dense but necessary and there is no 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?

With no output schema, the description carries the burden of explaining return values, and it does so well by detailing description, lineup, rank, predicted_end_time, and ticket_offer. It does not specify result ordering, pagination, or the full event object, which keeps it from a 5.

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, but the description adds meaningful usage semantics by indicating that location can be supplied as a city or as coordinates, and by characterizing all non-location inputs as optional filters. This clarifies the relationship between city, latitude/longitude, and radius_km.

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 opens with a specific action and resource ('Search for events near a location') and clarifies it is for finding events in a city or near coordinates. It is clearly distinct from sibling search tools like search_artists, search_organizers, and search_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 description explicitly states when to use the tool: 'Use this to help users find events in a city or near coordinates.' It does not explicitly mention alternatives or when not to use it, so it earns a 4 rather than 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?

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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the enriched data and scrape status, which is useful, but does not disclose behavior like pagination limits beyond the schema or what 'scrape status' means.

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 waste. The first sentence states the core function and the second lists the return fields. Information is front-loaded and every word 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 read-only search tool with 100% schema coverage and no output schema, the description is complete enough. It could mention pagination or the meaning of 'scrape status', but the annotations and schema cover the essential safety and parameter details.

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 four parameters. The description adds a high-level summary of what is returned but does not add meaning beyond the schema for individual parameters.

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') and resource ('organizer profiles enriched from event data'), and lists the exact fields returned. It clearly distinguishes itself from sibling search tools by focusing on organizers.

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

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

The description implies usage for finding organizers with contact details and scrape status, but does not explicitly state when to use this tool versus alternatives like search_artists or search_events. The context is clear enough for an agent to infer, 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.