find_newsletters

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

No annotations exist, so the description carries the full burden and does: it discloses that failing header sub-requests are silently dropped, explains the resulting discrepancy against bulk_by_query(only_newsletters=True), and warns that the List-Unsubscribe header marks bulk senders rather than junk. This is exactly the kind of failure-mode and misinterpretation context an agent needs.

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?

Front-loaded with the action and the detection rule, then the IMPORTANT caveat, then the return shape, then args — a sound ordering. It runs a little long, and the sentence about the model deduping 200 rows by hand is motivational rather than operational, but nothing is padding.

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?

With no annotations and no output schema, the description supplies the return shape ({checked, headers_ok, header_fetch_failed, newsletter_messages, senders}), the rationale for those fields, and the semantic trap to avoid. Nothing an agent needs in order to call it or interpret it is missing.

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%, so the description must compensate, and it documents all three parameters: folder accepts an id or well-known name, max_check bounds how many recent messages are scanned, and group_by_sender=False yields raw per-message rows. It does not give an example of a well-known folder name, which would have closed the gap fully.

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?

States a specific verb and resource ('Scan a folder for bulk mail... and report how each sender can be unsubscribed') and pins down the detection criterion (List-Unsubscribe header). It is clearly distinct from unsubscribe/unsubscribe_many (discovery, not action) and from bulk_by_query, which it names explicitly.

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?

Gives a strong exclusion ('Treat this as a list of candidates to show the user, never as a list to sweep') and explains why grouping is the default and when to set group_by_sender=False. It stops short of explicitly naming the sibling that performs the unsubscribe, leaving that hop implicit.

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