Approve guests

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

Goes well beyond the annotations: it discloses that Partiful texts or emails each approved guest (explaining why destructiveHint and openWorldHint are set), that invalid ids abort the call before it waits for confirmation, that the call has an approval gate, and that the caller must be a host. These are exactly the side effects and preconditions an agent needs before a mutating call.

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-loads the action and scope in the first two sentences, then tacks on preconditions and return shape in order of importance. The aside 'as Approve on the host's guest list does' is a small UI-mapping flourish, but no sentence is dead weight.

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 no output schema, the description usefully reports the return shape (approved count plus still-waiting count) and covers side effects and permissions for a destructive mutation. It does not say what happens if all and guest_ids are supplied together, which is the one unresolved ambiguity.

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%, so the schema carries the basics; the description still adds meaning by framing guest_ids as 'the given pending guests' versus all as 'everyone who is pending', and by stating the pending-only validation rule that the schema does not encode.

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?

Names a specific verb (Approve) and resource (pending guests on a Guest Approval event), and states scope: the given guests, or all of them. An agent can distinguish it from invite_guests and check_in_guests without opening either schema.

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?

"Hosts only" gives a prerequisite, and "Ids that are not pending are refused" tells the agent which inputs are valid, so the pending-only condition is explicit. There is no direct routing statement against siblings like check_in_guests, which is the remaining gap.

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