Scrape City

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 a meaningful behavioral detail: it collects 'visible attendees' and does 'not automatically RSVPing.' However, it does not disclose potential scraping behavior, rate limits, or platform-specific quirks beyond what the schema already covers, so additional context is limited.

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 a single sentence with no filler or redundancy. It front-loads the core action ('Collect events and visible attendees') and includes the critical side-effect constraint ('without automatically RSVPing'). Every word contributes meaningful information, making it an exemplary concise description.

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 has 7 parameters across 3 platforms and no output schema, so the description needs to provide an overview of pagination, return contents, and platform differences. It does not mention return format, how limit/offset apply per platform, or how 'visible attendees' are determined. The terse description leaves substantial gaps for an agent deciding how to invoke it 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 71%, so the schema already documents most parameters. The tool description itself adds no parameter-level meaning, and two parameters (limit, guest_limit) lack schema descriptions, though their names are fairly self-explanatory. The description neither compensates for the remaining gaps nor contradicts the schema, so a 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 uses a specific verb ('collect') and identifies a clear resource ('events and visible attendees'), so an agent can tell this tool gathers data. It also adds a key negative behavior ('without automatically RSVPing'), which somewhat distinguishes it from other tools. However, it does not explicitly compare against siblings like list_events or search_events, so it earns a 4 rather than a 5.

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 no explicit direction about when to use this tool versus alternatives. It implies a data-gathering use case but never names sibling tools like search_events or get_event_guests or explains when scrape_city is preferred. There is no guidance on when not to use it, so the agent is left to infer usage context.

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