get_thread

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

With no annotations, the description carries the full burden and does well by explaining the depth parameter's exact behavior (0, 1, 2, N, -1) and noting that top-level comments include reply_count. It doesn't mention potential side effects or rate limits, but for a read-only fetch the depth detail is substantive transparency beyond the schema.

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?

The description is appropriately sized, opening with a clear one-sentence purpose and then using a structured list for arguments. Every line adds meaningful information, with no fluff or repetition.

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?

Given the tool has a simple parameter set and an output schema, the description covers the essential behavior well, especially the depth options. It misses only an explicit note on how this relates to sibling get_comment_tree, which would strengthen completeness in the sibling context.

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%, but the description meticulously defines both parameters: story_id as 'The HN story ID' and depth with level-by-level semantics including special value -1. This fully compensates for the schema's lack of descriptions, going beyond mere names and types.

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 clearly states the tool fetches 'a story and its comment tree from Hacker News,' with a specific verb and resource. It doesn't explicitly differentiate from the sibling get_comment_tree, which could be ambiguous, but the mention of 'story and its comment tree' gives a distinct scope.

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 usage when the agent needs story metadata and nested comments, and the depth parameter provides guidance on how much of the tree to retrieve. However, it doesn't explicitly state when to prefer this over get_comment_tree or other sibling tools, leaving the when-to-use guidance implicit rather than direct.

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