scrape_single_note

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'scrape and analyze' but does not describe key behaviors such as network requirements, rate limiting, authentication (e.g., login status), error handling (e.g., invalid URL, note not found), or what 'analyze' specifically does. Without these details, the agent may misuse the tool or encounter unexpected failures.

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 extremely concise: two short sentences defining the purpose and context, followed by structured Args and Returns sections. Every sentence serves a clear function, and there is no redundancy. The format is easy to parse and front-loaded with the most critical information.

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's simplicity (2 parameters, no annotations, has output schema), the description covers the essential purpose, parameters, and return format. However, it lacks important context about behavioral aspects (e.g., rate limits, login requirements, error scenarios) that would help an agent use it reliably. Completeness is adequate for straightforward use but not comprehensive.

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 input schema has 0% description coverage, so the description is the sole source of parameter semantics. It provides meaning for both parameters: note_url is explained with an example URL, and max_comments is described as the maximum number of comments to scrape with a default of 100. This adds significant value beyond the schema's bare property titles. A slight deduction for not specifying format requirements (e.g., valid URL patterns) or edge-case behavior.

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's purpose: scraping and analyzing comments from a single Xiaohongshu note given a URL. It uses specific verbs ('抓取', '分析') and specifies the resource ('单篇小红书笔记的评论'). The sibling tools (run_search_task, analyze_comments, check_login_status) are distinct, and the description explicitly frames the use case as '已知笔记URL、只需抓取单篇评论的场景', which differentiates it from search or bulk tasks.

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 a clear usage context: when you have a known note URL and only need to scrape comments from that single note. However, it does not explicitly state when not to use this tool (e.g., for batch scraping or analysis without scraping), nor does it mention alternatives like run_search_task for searching notes or analyze_comments for analyzing already scraped data. The guidance is implied rather than overt.

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