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

Annotations declare destructiveHint=true and idempotentHint=false, but the description adds the substance an agent actually needs: existing bookings survive, new bookings stop using the connection, and the operation is gated behind a CONFIRMATION_REQUIRED/confirmToken handshake. That is real behavioral disclosure beyond the structured hints, not a restatement of them.

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 sentences, front-loaded with the destructive action and its scope, then the side effects, then the call protocol. 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 destructive two-call mutation with no output schema, the description covers blast radius, the confirmation protocol, and the retry contract. Gaps: no mention of what a successful response contains, what happens if the token expires or the second call is never made, and no routing to the specialized disconnect_* siblings.

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 baseline is 3. The description earns above baseline by encoding the contract the schema only half-states: the first call omits the token, the retry must carry the SAME arguments plus confirmToken, which is exactly the failure mode an agent would otherwise hit. It does not say anything about credentialId sourcing beyond what the schema already notes ("From list_connections").

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 concrete verb and resource set: "Remove a connected calendar, video app or payment account." That is far more specific than the bare name/title. However, it never distinguishes this tool from its near-identical siblings disconnect_calendar, disconnect_conferencing, disconnect_google_workspace and disconnect_sign_in_method — an agent cannot tell from the description which one applies.

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?

Usage context is clear: this is how you stop a service from being used for new bookings, and the two-call confirmation protocol is spelled out step by step, including the instruction to tell the user what stops working first. What is missing is any exclusion or routing rule against the specific disconnect_* siblings, so the agent still has to guess which disconnect variant to pick.

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