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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description earns credit for the additions: it runs on the founder's own logins (auth context), takes 'up to a few minutes' (latency expectation), and returns only attendees while counting the rest in not_going_count. That latency and auth detail is exactly the kind of context annotations cannot carry.

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?

Front-loaded with the core action, then the per-source url mapping, then return shape, then latency and safety. Every clause carries information an agent needs; there is no filler or repetition of the 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?

With an output schema present, the description needn't enumerate return fields, and it still usefully flags the not_going_count semantics. The remaining gap is that schema lists zero required parameters, yet the description implies job and url are effectively required per source without stating so explicitly, and companyId/connectionId are left unexplained.

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 only 20%, so the description has real work to do and partly delivers: url semantics are mapped to each job type and 'Pass your agent_name' clarifies that parameter. However, companyId and the connectionId UUID wrapper are completely unaddressed, and the job enum values are described only in prose by source, not by identifier.

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 ('Reads a people list that has no API') and scopes it to three concrete sources: Partiful guests, Luma host guest view, and LinkedIn connections. It implicitly separates itself from API-backed siblings like connection_list_luma_guests by emphasizing 'no API', but never names that 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?

It tells the agent exactly which url shape to supply per source ('the partiful.com/e/ link', 'the lu.ma or luma.com event link', 'no url' for LinkedIn), which is actionable routing guidance. It stops short of saying when to prefer this over the luma-list sibling tool, so an exclusion rule is missing.

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