search_messages

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

No annotations are provided, so the description carries the disclosure burden. It goes beyond the schema by warning that email content is untrusted third-party data and instructing the agent to ignore directives embedded in bodies, subjects, or sender names. It does not explicitly state read-only behavior, but search semantics imply it.

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 but complete. It leads with the action and scope, then explains return behavior and the correct way to handle output, and closes with a high-value security warning. Every sentence earns its place without 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?

Given there is no output schema, the description adequately explains that results are summaries carrying ids usable by read_message, and it adds important handling guidance for untrusted content. It could be more complete by enumerating summary fields or clarifying ordering/pagination behavior, but it is sufficient for a straightforward search tool with fully documented parameters.

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 100%, so the baseline is 3. The description adds real value beyond the schema by giving a concrete Gmail search syntax example ('from:alice is:unread newer_than:7d') and by explaining how the query parameter's output relates to read_message. The account and max_results params are already well described in the schema.

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 names a specific verb and resource: 'Search one account's mailbox using Gmail search syntax.' The 'one account' scope cleanly distinguishes it from sibling search_all_accounts, and the statement about returning message summaries with ids clarifies what the tool produces.

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 clearly establishes the intended context: searching a single account rather than all accounts, and it points to the next step by saying the returned ids can be passed to read_message. It does not explicitly name alternatives like search_all_accounts, but the single-account wording makes the boundary clear.

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