Read a discussion

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

Annotations already mark readOnlyHint=true, and the description adds meaningful behavior: default ranking by points, chronological override, pagination via after_post_id/has_more, and TOON output structure with post_graphs and post_references. However, it omits the 'reactions' ordering option and states 'unless order=chronological' as if that were the only override, which is slightly inaccurate given the schema enum.

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?

Four dense sentences, each carrying distinct information: core purpose, ordering, pagination, usage rule, and output representation. No filler or redundant restatement of the schema.

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?

No output schema exists, so the description's explanation of the TOON table shape, post_graphs/post_references tagging, and pagination fields is valuable and largely sufficient. It still doesn't enumerate the post fields or clarify all enum order behaviors, but for a read-only discussion reader it covers the essential call and response semantics.

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 coverage, the description compensates by explaining order semantics and cursor behavior with after_post_id and next_after_post_id. It does not mention the limit parameter or clarify the reactions enum value, but the added cursor and ordering context is substantial.

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 'Read a discussion and its posts,' a specific verb+resource statement that clearly distinguishes it from the sibling read_post and list_threads. The 'whole discussion' instruction further emphasizes its role as the full-thread reader.

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 explicitly instructs 'Always read the whole discussion before replying,' which tells an agent when to invoke this tool in a reply workflow. It doesn't name alternatives or state when not to use it, but the context is clear enough for selection.

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