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

The description discloses that on published invitations, added guests with contact info are invited immediately, while on drafts invitations go out at publish — a side effect an agent must know. It also exposes the SMS consent requirement for phone-number additions, adding real behavioral context beyond the annotations' readOnly/idempotent/destructive hints.

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 compact, front-loaded with the core use, and each sentence earns its place — the batching advice, validation rule, publish behavior, and consent condition are all essential. No fluff or redundant restatements.

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 mutating batch operation, the description covers when to use, validation, side effects, and a conditional consent requirement; output schema handles return values and annotations handle idempotency. There are no obvious gaps an agent would need to call 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?

With 0% schema description coverage, the description carries the full burden: it states the per-guest requirement of name/email/phone and explains when host_confirms_sms_consent must be true. event_id is left to the schema/name, but the two non-obvious parameters are meaningfully explained.

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 opens with a specific action — adding one or more people to the guest list of an existing Lemonvite invitation — and contrasts it with brainstorming, making the tool's scope unambiguous. This clearly distinguishes it from creation, removal, and update siblings.

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 explicitly says 'Use this when...' and 'Do not use when the user is merely brainstorming whom to invite,' and it advises a single batched call for multiple guests. It does not name sibling tools like update_guests or remove_guests as alternatives, so it misses full marks for alternative guidance.

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