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

With no annotations, the description carries full burden. It discloses content truncation, the empty-page behavior for HOT when no recent articles, and the requirement that both forum names be provided or the request is rejected. It implies a read-only operation via 'list' but doesn't explicitly state it; still, the behavioral quirks are well covered.

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 slightly long but efficient, front-loading the purpose before explaining constraints. Every sentence adds necessary context: the board pairing, sort behavior, and truncation notice. It could be tightened but remains scannable and informative.

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 5 parameters and no required fields, the description covers critical usage constraints (pair requirement, sort values, truncation) and the behavioral quirks (empty HOT page). It doesn't detail the return structure (no output schema), but 'list articles' implies a list. It adequately prepares the agent to call the tool correctly.

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. The description adds value by explaining the pair requirement for forumName and subForumName (schema only says 'pair with subForumName' without the rejection detail), elaborates on the sort semantics (engagement-ranked over a recent window, possible empty page), and clarifies that content is truncated. This goes beyond the schema's parameter 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 description clearly states the tool lists published articles from a specific Taiwan community forum, with a verb and resource. It distinguishes itself from siblings like get_article (by noting content truncation and redirecting there) and other list tools by focusing on articles. The context about the news-digest board and date range adds specificity.

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 clear instructions: both forumName and subForumName are required together (else rejected), sort options are explained (HOT for trending, LATEST for recent), and it explicitly directs users to get_article for full content. It does not mention alternatives like search_forum or list_comments, but the purpose is distinct enough. It could be more explicit about when to use this vs. search tools, but the guidance is solid.

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