Timbre

Overview Schema Source Related Servers Discussions Admin

save_search

Idempotent

Save a mail search under a reusable name to rerun it later, optionally create a Mail smart mailbox, preview current matches, or delete it.

Instructions

Keep a search under a name: search_mail with saved set to that name runs it, and what else is given narrows it. It says how many messages it finds now (preview: true only counts). in_mail: true also makes it a smart mailbox in Mail (only while Mail is closed; from, subject and words only). delete: true removes one. list_mailboxes lists both kinds.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "save_search"
  }
}

Input Schema

Name	Required	Description
`to`	No
`from`	No
`name`	Yes	Its name.
`query`	No	As in search_mail: words and operators, e.g. "facture newer_than:30d".
`delete`	No	true: delete the saved search (or smart mailbox) of that name.
`unread`	No
`account`	No
`flagged`	No
`in_mail`	No	true: a smart mailbox in Mail too (only while Mail is closed). Mail's can hold from, subject and words.
`mailbox`	No
`preview`	No	true: only count what it finds now; nothing is saved.
`subject`	No
`has_attachments`	No

Output Schema

Name	Required	Description
`name`	Yes
`note`	Yes
`status`	Yes	preview, saved, replaced, deleted.
`matches`	No	Messages it finds now.
`undo_token`	No
`matches_at_least`	No	There are more: the count stopped there.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.2Nov 9, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Beyond the annotations, the description discloses real behavioral traits: preview performs a count without persisting anything, in_mail only works while Mail is closed, and smart mailboxes are restricted to from, subject and words. That constraint detail is not derivable from the schema at all. The delete mode sits in mild tension with destructiveHint=false, but it is presented as an explicit opt-in mode rather than contradicting the annotation's intent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and there is little outright filler, but the second sentence ("and what else is given narrows it") is grammatically loose and forces the reader to infer which parameters it covers. Four dense, comma-spliced clauses in one block reduce scanability for a 13-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since an output schema exists, return-shape explanation is not required, yet the description still notes it reports how many messages it currently finds. For a 13-param tool with idempotent/non-destructive annotations, the mode explanations plus the Mail-closed caveat cover what an agent needs to call it correctly; only the unnamed filter parameters remain underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 13 parameters and only 38% schema description coverage, the description must compensate, and it partially does: "what else is given narrows it" groups the nine undocumented filter parameters as search filters, and the pointer to search_mail covers query syntax. However, individual parameters such as account, mailbox, flagged or has_attachments get no meaning beyond that inference, leaving a real coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Keep a search under a name" is a specific verb+resource, and the description immediately contrasts it with search_mail (which runs the saved search) and list_mailboxes (which enumerates both kinds). An agent can tell this is the persistence/creation counterpart to search_mail without opening the schema. It loses a point only because the purpose statement is buried in a telegraphic sentence that also covers two side modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is described per-mode rather than per-situation: delete: true removes, preview: true only counts, in_mail: true also builds a smart mailbox. The relationship to search_mail is stated ("search_mail with saved set to that name runs it"), which is genuinely useful routing. But there is no guidance on when to prefer this over save_template or create_rule, and no explicit exclusions beyond the Mail-closed caveat.

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