trigger_crawl

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains that the tool triggers a crawl, optionally saves to local, and optionally includes URLs, which indicates it may perform write operations. However, it does not disclose the impact on system state, resource usage, or potential side effects. The behavior is partially transparent but could be more explicit about side effects (e.g., network requests, data storage).

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, with a brief intro, parameter explanations, return description, and examples. It is front-loaded with the main purpose and efficiently covers each parameter. The structure is clear and each sentence adds value. Minor: the Args section repeats the parameter names already in the schema, but that's acceptable because it adds contextual meaning.

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 that the tool has 3 parameters, all optional, and an output schema exists (though not detailed here), the description covers the essential context: purpose, parameters, return type, and examples. It does not mention potential errors, rate limits, or specific platform IDs, but for a tool with no required parameters and an output schema, this is fairly complete. The examples clarify usage. It's slightly above average.

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%, meaning the description is the only source of parameter rationale. The description explains each parameter: platforms (list of platform IDs), save_to_local (whether to save to output), include_url (whether to include URLs to save tokens). This adds meaning beyond the schema, which only provides types and defaults. However, it does not elaborate on valid platform values or the format of the 'output' directory, but it does what is needed given the schema's lack of 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 action (trigger a crawl), the resource (crawl task), and key options (platforms, persistence, URL inclusion). It distinguishes itself from siblings like get_latest_news (which retrieves data without triggering) and get_rss_feeds_status (which checks status). Being specific about the trigger action and optional persistence helps the agent understand its unique role.

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 includes examples of usage (e.g., trigger_crawl(platforms=['zhihu'])) that demonstrate how to call it, but does not explicitly state when to use this tool versus alternatives or any exclusions. It implies this is for manual crawling, but lacks direct comparison to siblings that might be alternatives (e.g., if the user just wants latest news, they might use get_latest_news instead). The context is clear but not deeply elaborated.

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