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

Annotations say readOnlyHint=false on a 'List' tool, which would otherwise look contradictory; the description resolves this by disclosing the side effect precisely: 'If no watch exists, this creates an active manual-reply watch and starts background polling… existing watches are reused' — which also justifies the idempotentHint. It further discloses which platforms yield nothing and why, a behavioral fact not present in any structured field.

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?

Dense but front-loaded: purpose, then platform constraints, then side effects, then the disambiguation. The supported-platform list is repeated almost verbatim in the schema's `platform` description, which is mild redundancy, but every sentence carries a distinct fact.

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 tool with a hidden write/polling side effect and a nested request object, the description covers the critical behavioral risk and the output contract, and an output schema exists so return shape needn't be spelled out. The remaining gap is that the `request` envelope itself is never explained, though all its children are documented in schema.

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?

The top-level `request` wrapper has no description (reported coverage 0%), and the description adds no guidance on page/size/status semantics or on the interaction between `status` and the manual-reply workflow. The nested properties are self-documenting in the schema, so a baseline 3 is right; the only added value is the mention of the returned comment_id.

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 ('List real comments left by other people on the published social platform post') and immediately scopes it to a concrete data source (manual_reply_comments). It explicitly disambiguates from the sibling get_internal_comments at the end ('Postey's internal team comments come from get_internal_comments').

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 explicit when-to-use coverage per platform (served vs. refused) and pre-empts the most likely wrong move: 'get_internal_comments is not a fallback for them, since it returns private team notes.' It also points forward to the downstream tool ('Returns the comment_id that reply_comment needs').

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