stubhub_category_events

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that results are 'paginated' and that a 'zero count with an empty events list is a valid no-results response,' which prevents false error interpretation. However, it does not disclose page size, ordering, default radius, rate limits, or response shape beyond what is implied.

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 with no filler. The primary purpose is front-loaded, followed by scoping details and a useful edge-case clarification. The second sentence is slightly long with a parenthetical, but overall it is economical and well-ordered.

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 8-parameter tool with 3 required params, no output schema, and no annotations, the description covers the essential calling context: single category, location/radius/date filtering, pagination, and the no-results case. It does not describe the return fields, default page size, or error semantics, which are gaps an agent might need when consuming the response.

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 baseline is 3. The description adds modest semantic value by explaining that a category is 'a sport league, team, or a top-level vertical' and by summarizing the filter dimensions (location, radius, date range). It introduces no new format details 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?

The description states a specific verb and resource: 'List StubHub events in one category near a location.' It clarifies the scope ('single StubHub category (a sport league, team, or a top-level vertical)') and points to stubhub-categories for category ids, which distinguishes it from category-discovery and venue-focused siblings. It does not explicitly name an alternative event-search tool like stubhub_search or stubhub_venue_events, so differentiation from those is only implicit.

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 when to use the tool — for category-scoped, location-filtered event listing — and provides a pointer to stubhub-categories for discovering category ids. It does not explicitly state when not to use it or name alternatives (e.g., venue-specific or broader search tools), leaving some inference to the agent.

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