bulk_by_query

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

With no annotations, the description carries the full burden and does most of it: it discloses that dry_run is TRUE by default and what it returns, that on_protected skips protected senders by default, that date/sender filters are applied client-side, and that only_newsletters costs an extra header pass. It stops short of stating whether delete is permanent or recoverable and what the final report looks like.

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?

Long but front-loaded and organized as one labeled block per parameter, so an agent can skim to the field it needs. A few parenthetical asides (the 'old <topic>' sweep example, the newsletter-vs-junk lecture) run longer than strictly necessary, but nothing is wasted filler.

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 12-parameter, no-annotation, no-output-schema mutation tool this is close to complete: safety defaults, filtering composition rules, and protected-sender behavior are all covered. The remaining gaps are max_results truncation behavior and the shape of the non-dry-run result.

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 for all 12 parameters, and it explains roughly ten of them including the undocumented-in-schema action enum values and the destination_folder requirement for move. max_results is only mentioned in passing as an upper bound with no default or truncation semantics, and folder's default of inbox is left implicit.

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 — find every message matching a query and apply one action to all of them in a single call — plus the distinguishing benefit (ids never enter the conversation). It is clearly the general filter-driven counterpart to the action-specific siblings (bulk_archive_messages, bulk_move_messages, etc.).

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?

Explicitly prescribes the dry_run-then-rerun workflow, spells out the on_protected policy choices, and tells the agent when to prefer received_before/after over a Graph date $filter and when to use senders_only instead of a sender $filter. It even routes the agent to sender_summary for picking addresses.

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