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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the actual write mechanism and blast radius: it always produces a card in the person's Stream, the tap is what commits the change, and the notify set includes players, parents who asked to be told, and the carpool, plus the group-chat message. That explains why the operation is non-destructive/idempotent (a cancelled session can be restored) and is genuinely beyond what the structured fields convey.

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 purpose, then mechanism, then session-selection, then the usage gate — a sensible order. It is a single dense paragraph with several em-dash asides and the vague phrase 'through every check the app has', so it is readable but not maximally tight.

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 values need no explanation, and annotations carry the safety profile. The description covers all four modes, target identification, notification side effects and the usage gate, but says nothing about failure/preconditions (what if the person does not lead the group) or how long the Stream card remains actionable.

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 100% schema coverage the baseline is 3, and the description does add real meaning: the message is sent in the person's own voice and appears in the group chat as theirs, and 'Leave out to only notify' clarifies message optionality. However, it states the message is '≤ 500 characters' while the schema allows maxLength 1000, a conflicting limit that could cause an agent to reject valid input.

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+resource immediately: suggest moving/cancelling/changing the place of one session of a group the person leads, or restoring a cancelled one. It is unmistakably distinct from neighbors like add_session (create), message_group (plain messaging) and read_schedule (read), and the title's word 'suggest' is immediately clarified by 'the tap makes the change'.

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?

Gives an explicit gate ('Only when they ask') and tells the agent how to identify the target session: by `key` from read_schedule, or by `sessionDate` (+ `sessionTitle`). It does not explicitly name the sibling to use instead when the intent is a brand-new session or a pure broadcast, 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.