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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior beyond annotations: the tool issues a short-lived, bound preparation token — a side effect that no annotation captures. The 'short-lived' and 'bound' qualifiers inform the agent about token lifecycle and coupling to specific inputs. It does not disclose failure behavior or what happens when validation fails, but the token disclosure is real added value with no contradiction to annotations.

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?

A single 17-word sentence that is front-loaded with verb and resource, with zero filler. Every element carries information: 'Purely' scopes the action, 'note or media listing' names the resource, 'short-lived bound preparation token' describes the outcome.

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 and annotations are rich, which covers return values and safety. But critical gaps remain: the noteId/mediaId/fileId aliasing is unresolved, 'ready' is undefined, and the downstream consumption of the preparation token is unclear. For a 6-parameter tool with 0% schema coverage, the description needed to do substantially more work to make correct invocation possible.

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 description coverage is 0%, so the description carries the burden of explaining parameters — and it barely does. It hints that the kind enum maps to 'note or media listing,' but it never clarifies the relationship among fileId, noteId, and mediaId (three structurally identical $ref aliases), nor which ID to pass for which kind. amountMinor, currency, and what the token is 'bound' to are left unexplained. An agent cannot determine correct parameter selection from either the schema or the description.

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 names a specific verb ('validate'), a clear resource ('note or media listing'), and a concrete outcome ('issue a short-lived bound preparation token'). The 'Purely' prefix effectively signals this is not a publishing action, distinguishing it from siblings like publish_note_listing and publish_media_listing. However, it does not explicitly name any sibling it is not, and 'when ready' leaves the readiness condition vague.

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?

The description implies a pre-publish validation context: an agent would call this to check readiness and obtain a preparation token before publishing, rather than to publish directly. But it never explicitly states when to use this tool versus publish_note_listing, publish_media_listing, or prepare_checkout, nor does it give any exclusions or alternatives. The guidance is implied, not stated.

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