gigstamp

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

No annotations are provided, so the description carries the burden. 'Get' safely implies read-only and the supported-city scoping is stated, but it says nothing about behavior when the slug is valid for a different city, when no gig matches, or what the response contains. That is a meaningful but not severe gap for a simple read operation.

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 with the resource and both scoping constraints and no filler. It is appropriately sized for a two-parameter lookup, though it is terse enough that it could have spent one more clause on failure behavior without becoming bloated.

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 two-parameter lookup with no annotations and no output schema, the description covers what is needed to invoke it but leaves the return shape and not-found behavior unstated. Given the absence of an output schema, a brief note on what a successful or failed lookup yields would round it out.

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

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

Schema description coverage is 100% and the city enum is fully enumerated in the schema, so the schema already documents both parameters. The description restates the same scoping (slug + supported city) without adding format, case-sensitivity, or matching semantics, so the 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 names a specific verb and resource ('Get one gig') and scopes it to a slug within a supported city, which cleanly separates it from the batch-oriented sibling search_gigs_and_events. It does not explicitly name that sibling as the alternative, but the single-item retrieval intent is unambiguous.

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

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

Usage is only implied: the phrase 'by its slug within a supported city' signals that the caller must already know the slug and city, which is the de facto precondition. There is no explicit when-to-use/when-not guidance or reference to search_gigs_and_events for lookup-by-criteria, so an agent must infer the routing.

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?

No annotations provided, but description adds key behavioral context: returns city names and URLs, and indicates it's a prerequisite. However, it doesn't explicitly state read-only or auth needs, but given simplicity, it's sufficient.

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, no extraneous words, front-loaded with action and result. Efficient and focused.

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 list tool with no parameters and no output schema, the description is complete: it explains what it returns, when to use it, and its role relative to other tools.

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?

No parameters, so baseline 4 per instructions. Description adds meaning beyond schema by specifying output (cities and URLs), even though schema has no properties.

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 tool lists cities with their listing URLs, using a specific verb and resource. It distinguishes from siblings (get_gig, list_venues, search_gigs_and_events) which focus on other entities.

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 advises 'Call this first: only these cities return data,' providing clear when-to-use guidance and implying prerequisites for other tools.

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

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

With no annotations, the description carries the full burden. It does disclose a non-schema behavioral detail — that each returned venue carries a grassroots|major scale — but omits pagination, completeness of results, auth needs, and return shape for what is otherwise an opaque list operation.

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

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

Two tight sentences, front-loaded with what is listed and where, followed by a useful detail about the scale field. Minimal waste, though 'gigstamp tracks' is slightly awkward phrasing.

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 one-parameter read tool with no output schema, the description plus annotations are nearly sufficient, and it volunteers the shape of a returned attribute (scale). A note on result scope or pagination would make it fully complete.

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

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

Schema coverage is 100% with a single enumerated city parameter fully documented in the schema, so the baseline is 3. The description's 'supported city' phrasing echoes the schema's constraint without adding format or validation detail beyond 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?

States a specific verb (List) and resource (venues) with clear scope: venues tracked in a supported city. It distinguishes itself from list_cities/get_gig/search_gigs_and_events by describing its returned entity and its grassroots/major scale, though it does not name an alternative 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?

Usage is implied rather than stated: 'in a supported city' signals the required city scoping, and the required city enum makes the precondition inferable. However, there is no explicit when-to-use vs search_gigs_and_events or list_cities guidance, and no exclusions.

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?

With no annotations, the description carries the full burden and does so well: it discloses result ordering ('most imminent first'), return contents (booking link out, gig-page url to cite), and the commercial constraint ('gigstamp does not sell tickets'). This is exactly the behavioral context an agent needs beyond the 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 dense paragraph with the core search action and coverage front-loaded, and every clause carries information. The parenthetical 'the local grassroots scene is front and centre, but coverage aims to be complete' is mildly promotional and slightly hedged, keeping it short of a 5.

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 an 11-parameter search tool with no output schema, the description covers content scope, ordering, returned fields, and the supported-city constraint, so an agent can call it and interpret results without further inference. Nothing essential 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?

Schema description coverage is 91%, so parameters are already well documented, and the description largely restates the filter dimensions (date range, venue, category, scale, free text) without adding syntax or format detail. It adds marginal value, e.g. glossing the grassroots/major scale split, 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?

States a specific verb and resource (search gigs and events) and enumerates the exact content types covered: band gigs, open mics, comedy nights, jam/folk sessions, festivals, club nights. It clearly distinguishes itself from siblings by scoping to a single city ('a supported city's upcoming...') while get_gig, list_cities and list_venues handle single-record lookup and reference data.

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

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

Gives clear context for use and routes the agent to list_cities for supported coverage ('Only supported cities return data (see list_cities)'), plus lists the filter dimensions available. It stops short of explicit when-not guidance or naming alternatives for retrieving a single event (get_gig), so it is not quite a 5.

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