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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the return shape (short passages with links) and the privacy guarantee that it never reads any group, which no annotation conveys.

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 purpose followed by the topic enumeration and return format in one readable sentence. The topic list is long, but each item earns its place by signalling coverage; no filler sentences.

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?

An output schema exists so return details are not strictly required, yet the description still notes passages and links. Combined with the privacy note and topic coverage, an agent has what it needs; only the sibling-selection rule is unstated.

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?

There is one parameter with 100% schema description coverage, including a worked example, so the schema carries the semantics. The description's topic list hints at acceptable question content but adds no format or length guidance beyond what the schema already states, making 3 the correct baseline.

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?

States a specific verb and resource: answering how-to questions about running a gift exchange with Shuffleroo. The help/answer scope clearly distinguishes it from the sibling prepare_gift_exchange, which performs an action rather than answering questions.

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 enumerated topics (couples apart, late joiners, gift limits, privacy, no app needed, group sizes, anonymous questions, no repeats, work use) give the agent a clear sense of when this tool applies. It does not explicitly say when to prefer prepare_gift_exchange over this one, so it stops short of full when/when-not routing.

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