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

The annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description's additional contribution is the access requirement "Needs pods:read" and the scope note about up to three pods. Both are useful context an agent cannot get from the annotations or schema. It stops short of 5 because ordering, result limits, and whether past nights are excluded are not addressed, though "upcoming" does imply a forward-looking window.

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?

It is three tight sentences front-loading the resource definition, then the optional filter, then the permission requirement. The enumeration of returned fields is dense but justified because no output schema exists. Slightly awkward parenthetical placement keeps it from a 5.

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 is simple: one optional parameter at 100% schema coverage, no output schema. The description compensates for the missing output schema by describing each returned field, states the permission prerequisite, and clarifies the multi-pod default. Nothing an agent needs in order to call it correctly is absent.

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 baseline is 3 and the schema already documents pod_id as a UUID filter. The description goes slightly beyond it by pairing "Pass pod_id for one pod's" with the multi-pod default implied by the "up to three" parenthetical, which tells the agent that omitting the parameter means all of the user's pods rather than an error or empty result.

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 concrete resource for the noun ("the upcoming game nights the user's pods have planned") and enumerates what each entry carries (pod, time, place, formats, headcount, the user's own answer). This makes it clearly distinct from the deck- and collection-related siblings. The action itself is implicit rather than stated as an explicit verb like "list" or "retrieve", which keeps it just short of 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?

"Pass pod_id for one pod's" gives a scoping cue, and the "(a user may be in up to three)" parenthetical implies that without pod_id the result spans all of the user's pods. However, there is no explicit statement of when to use this versus other tools, no when-not guidance, and no note about what happens when the user belongs to no pods or has no upcoming nights.

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