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

Annotations already declare destructive=true and idempotent=true, yet the description still earns credit: it explains the seven-day expiry cap, that retry identity means same clientId plus unchanged body, and that the result is revision-bound with no read attestation or human acceptance. The main gap is that destructiveHint is never unpacked — the description does not say whether an existing check-back is replaced or what is lost.

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 core action, then scope exclusion, then call semantics and return behavior. No filler and no repetition of the title.

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 mutation tool with a nested command object, a four-way trigger union, and no output schema, the definition is thin — it says nothing about trigger kinds, what 'revision-bound' means for the caller, or what 'without read attestation or human acceptance' implies operationally. It is adequate for identification but not for correct invocation.

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 only 50% schema description coverage, the description should compensate, and it names clientId, baseRevision, purposeRevision and snapshotId — but only conveys meaning for the retry-identity params. The actual payload (checkBack.at, triggers, reason, expiresAt), the room_id, and the four trigger kinds receive no explanation, leaving the most complex nested object unglossed.

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 specific verb and resource ('Records a ... check-back declaration') and adds the seven-day expiry constraint, which is not in the schema. It also carves out scope against the scheduling family ('Does not create a scheduler'), helping separate it from set_check_schedule, though it never names the sibling it is contrasted with.

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?

'Does not create a scheduler' is the only routing signal; there is no explicit statement of when to use this versus set_check_schedule, purpose_renew, or purpose_cancel_check_back, all of which sit in the same sibling cluster. Usage is implied by the purpose statement rather than stated.

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