extract_by_selector

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

With no annotations, the description carries the burden of behavioral disclosure. It explains key behaviors: resolving relative URLs to absolute, row_selector producing table rows, and save_as storing rows. However, it does not disclose potential side effects like whether it performs writes (e.g., saving to DB) or the exact behavior of js_render, leaving some ambiguity for a tool that could be both read and write.

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 dense but well-structured, offering essential details in three sentences with a clear logical flow: purpose, field mapping, row selection, attribute extraction, and storage. It uses inline code for parameters and a compact JSON example, earning its length without fluff. Slightly long but justified by the need to explain complex features.

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?

The tool is complex (6 params, nested fields, output schema) and the description covers most usage aspects: selectors, attributes, row-based extraction, and save behavior. It omits details on js_render and exact return structure, but with an output schema present, that is acceptable. Overall, it provides sufficient guidance for effective use in a scraping workflow.

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 0%, so the description must explain all parameters. It covers fields with an example, row_selector semantics, the @attr suffix, and save_as/mode usage. It does not explicitly describe urls (obvious) or js_render, but the core semantics are well-addressed, exceeding the baseline 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 it extracts arbitrary fields from pages using CSS selectors, positioning it as the general-purpose alternative to fixed extractors. It explicitly names the key parameters (fields, row_selector, save_as) and even provides a JSON example, making the tool's purpose unmistakable.

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?

It explicitly says this is 'the general case the fixed extractors do not cover', directly contrasting with sibling tools like extract_products and extract_links. It also gives concrete usage patterns: using row_selector for listings, attribute suffix for hrefs, and append mode for batching, which instructs when and how to apply the tool.

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