get_post

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

There are no annotations, so the description must carry the full burden of disclosing behavior. It states it fetches full text and comments, implying a read operation, but it doesn't explicitly confirm read-only, mention any authentication requirements, or note limitations like failure modes or rate limits. It also doesn't explain what happens with the 'with_comments' toggle beyond the schema default. Given no annotation coverage, this is a notable gap.

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 concise and well-structured: a one-sentence overview followed by a clear Args list. No fluff or redundant information. The main purpose is immediately stated, and parameters are explained in a compact bullet-like format. Every sentence adds value.

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?

There is an output schema, so return-value details are not needed in the description. The description covers the core function and parameter semantics, but it lacks guidance on when to choose this tool over sibling tools, nor does it mention any side effects or prerequisites. For a relatively simple fetch tool, this is adequate but not comprehensive, especially given the many sibling tools in the 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?

The schema description coverage is 0%, so the description must compensate, and it does well. The Args section explains post_id can be a numeric ID or a full link, with_comments controls whether comments are included, and comment_count has a max of 30 – none of this is in the schema. This provides critical semantic guidance that the schema alone lacks, so a high score is warranted.

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 function: '按帖子 ID 取全文及热门评论' (get full text and popular comments by post ID). It identifies the resource (post), the operation (fetch), and the scope (full text + comments). While it doesn't explicitly contrast with siblings like get_hot_posts or search_posts, the name and the description are unambiguous enough that an agent can infer its role, especially with the hint that IDs come from discussion or hot-post lists.

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 provides implicit usage context: it says the ID can be obtained from a discussion list or hot-post list, which suggests when one might have a post ID at hand. However, it doesn't explicitly state when to choose this over alternatives like search_posts or get_user_posts, nor does it give exclusions. This is more than no guidance but less than explicit recommendations, so a 3 is appropriate.

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