stubhub_venue_events

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the data is 'scraped from its StubHub page,' mentions the returned fields (event name, date, starting price), and explains that an empty list with zero count is a valid response. This is helpful. However, it does not disclose potential rate limits, failure modes, or any side effects, though the tool is clearly a read operation. It also does not mention authentication requirements, which may be relevant for a scraping tool.

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 moderately long but each sentence adds useful information. The purpose is stated first, followed by the data fields, the parameter acquisition method, and the valid empty response. It is well-organized and avoids redundancy. The only minor issue is that the sentence about obtaining the pair could be slightly more concise, but it is not 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 tool with no output schema, the description provides essential return information (event name, date, starting price) and the edge case of an empty list. It also explains how to get the required inputs. It does not mention pagination or error handling, but for a simple list operation, these are likely less critical. Overall, the description covers the key aspects an agent needs to call the tool 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?

The schema already provides full coverage for both parameters (venue_id and venue_slug) with types and an example slug. The description adds substantial value by explaining how to obtain a valid pair from another endpoint's event URL, providing a concrete example URL with the slug and id extracted. This provenance information goes beyond the schema and helps the agent correctly construct inputs.

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's purpose: 'List a StubHub venue's upcoming events.' It specifies the resource (a StubHub venue), the action (list events), and the data fields (event name, date, starting price). It also differentiates by focusing on 'a venue's own upcoming event calendar,' distinguishing it from performer- or search-based tools. The description is specific and 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?

The description gives important guidance on how to obtain the required parameters: 'Obtain a real venue_slug+venue_id pair from another endpoint's event url field.' This is useful operational guidance. However, it does not explicitly state when to use this tool versus alternatives like stubhub_performer_events or stubhub_search, nor does it mention exclusions. The context implies it is for a specific venue page, but the distinction from siblings is implicit rather than explicit.

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