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

The annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) already convey mutation semantics and external dependency. The description adds genuinely new behavioral context: the token can be revoked CRM-side and this manifests as a silently dead integration, explaining what the 'check' action actually diagnoses. It does not contradict the annotations, though it stops short of describing activation side effects.

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 and the operation list, then the boundaries and routing. It is dense and slightly long, but nearly every clause carries distinct information (what it does, what it diagnoses, what it excludes, where to go instead).

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 no-output-schema mutation tool, the description covers operations, the diagnosis scenario, and sibling routing. It is complete enough to call correctly; only the exact shape of the 'show' state return is left implicit, which is a minor gap.

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 enum meanings are already documented in the schema. The description nonetheless enriches the 'check' action with the token-revocation rationale, adding meaning beyond the terse schema enum text, while quiz_id and crm need no elaboration.

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?

Names a specific verb+resource (sending quiz answers to amoCRM/Bitrix24) and enumerates the concrete operations: shows whether sending is on, enables/disables it, and checks connection liveness. It also explicitly carves out what it does NOT do (field mapping) versus the sibling manage_quiz_crm_mapping, so an agent can distinguish them without opening schemas.

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?

Explicit when/when-not routing: field mapping is done in the cabinet, portal connection is elsewhere, and overall integration state lives in get_quiz_integrations. The alternative tool is named directly, leaving nothing to inference.

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