Post Comments

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

Beyond the annotations it discloses the two traits that matter most operationally: the call consumes paid API credits and requires confirm=true, and read-like POSTs do not publish to social platforms (which explains the readOnlyHint=false). It also documents pagination constraints (no cursor batching or comma-separated cursors). It stops short of describing error/failure behavior or credit amounts.

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?

Purpose and return shape are front-loaded, and the long field list earns its space because there is no output schema. It is somewhat over-packed: pagination and cursor rules, GET/POST guidance, trim, and credit/confirm notes are run together in a single block, and the credit warning is appended at the end rather than near the top where a cost-bearing requirement would be more visible.

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?

With no output schema, no required parameters, and a nested payload object, the description does the heavy lifting well: it describes both the post fields and the comment object fields including nested replies, plus pagination and credit behavior. Only edge behavior (invalid URL, exhausted cursor, interaction of payload vs payload_file) is left undocumented.

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 baseline is 3, but the description adds real semantics the schema lacks: cursor must be a single opaque value taken exactly from more.cursor or replies.more.cursor, cursor batching is unsupported, POST should carry the same parameters in the JSON body, and trim exists to lighten responses. That is meaningful guidance beyond the field descriptions.

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 opening sentence gives a specific verb (retrieves) and resource (comments and post details from a Reddit post by URL), and the scope statement distinguishes it from the post-only sibling reddit_post. The returned-field enumeration reinforces that this is the comments-plus-post tool rather than a plain post fetch.

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?

It gives explicit conditional guidance on the GET vs POST path ("Use GET for normal requests", switch to POST when the opaque cursor grows too large) and on when to use trim. It does not, however, name the sibling tools (reddit_post, reddit_post_transcript) an agent would otherwise consider, so routing between Reddit tools is still left to inference.

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