watch_search

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

No annotations are provided, so the description carries the full burden. It discloses that this is a FOSS (open-source) alerts service and lists supported sources with carsales as default. It also implies statefulness by referencing check_watch to see new listings since the last check. However, it does not mention authentication requirements (e.g., set_auth), whether the watch persists, what the tool returns on success, or any error scenarios. With several behavioral unknowns, this is adequate but not comprehensive.

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 two sentences plus a source list, totaling ~30 words. It is front-loaded with the core action and workflow. The parenthetical "(FOSS alerts - no paid service)" adds a selling point but is not essential to usage, making it slightly extraneous. Overall, it is concise and well-structured, though a shorter version could omit that detail.

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 9 parameters, no output schema, and no annotations, the description should provide more context to ensure correct usage. It gives the essential workflow (save then check_watch) and lists sources, but it does not explain prerequisites like authentication (set_auth), how the watch interacts with other tools (list_watches, remove_watch), or what happens when the watch is saved successfully. This is sufficient for a basic understanding but leaves several operational details undocumented.

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?

The input schema has 100% coverage with descriptive parameters for all 9 fields. The description adds only the source defaults (carsales, gumtree, facebook) which the schema already covers via the sources parameter description. There is no additional explanation of parameter semantics beyond what the schema provides. Since the schema does the heavy lifting, a baseline of 3 is appropriate; the description does not add meaningful value.

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 uses the specific verb "Save" with the resource "a search to watch for NEW listings", which clearly indicates this tool creates a persistent watch on a search query rather than a single listing. It also mentions re-running check_watch, which differentiates it from immediate search tools like search_cars. This makes the tool's purpose unambiguous and distinct from its siblings.

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?

The description provides a clear usage pattern: save a search first, then re-run check_watch later to see new listings. This implies the tool is for ongoing monitoring, not immediate results. However, it does not explicitly state when to use this over search_cars or other search tools, nor does it mention alternatives like search_facebook_cars. The guidance is clear for the intended workflow but lacks explicit exclusions.

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