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

Annotations already declare destructiveHint=true, so the bar is lower, yet the description still adds substance the annotations cannot carry: cascade behavior ('every event on it'), the hard restriction that the primary calendar is ineligible, and an explicit non-recoverability warning plus a confirmation protocol. That is exactly the pre-call context an agent needs before issuing an irreversible mutation.

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?

Three short sentences, front-loaded with what is destroyed, then the eligibility constraint, then the warning and confirmation instruction. No filler and nothing buried.

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 two-parameter irreversible delete with no output schema, the description covers impact, eligibility, and the human-confirmation requirement well. The one gap is mechanical: how to obtain a valid calendarId and how the tool fails when an invalid or primary id is supplied.

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 50%: mailbox is documented and even points at list_authorized_mailboxes, while calendarId has no description at all. The description contributes indirectly by defining the target as a 'secondary calendar', but never tells the agent where to source a valid calendarId (list_google_calendars) or what happens if a primary id is passed.

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 (delete_google_calendar) plus the exact scope: only secondary calendars, and every event on the calendar goes with it. That scope statement distinguishes it from delete_google_calendar_event (single event) and from the parallel delete_outlook_calendar sibling without the schema needing to be opened.

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 a real precondition ('the primary calendar cannot be deleted') and an explicit operational instruction ('ask the user to confirm before calling this'), which is the correct routing signal for a destructive tool. It stops short of naming an alternative path (e.g., deleting events individually with delete_google_calendar_event) when the user only wants to clear the calendar.

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