create_watch

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

Annotations only declare the safety profile (not read-only, not destructive, not idempotent, open-world), while the description supplies the substantive behavior: no scheduled/background polling, folder membership refreshed between passes, new members starting at the previous completed pass, positions persisting until explicit deletion, and a 35-second creation deadline with retry delays. 'Identical creation retries preserve positions' adds nuance beyond the annotations without contradicting idempotentHint=false, since it is retry semantics rather than full idempotency.

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 purpose and the source-selector constraint are front-loaded, and the remaining sentences are short, clause-per-line statements with little filler. It is dense with distinct facts, though the paragraph form makes some operational details (deadline, retry) easy to skim past.

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 creation tool with no output schema and four undocumented parameters, the description covers lifecycle (persistence until deletion), concurrency (shared clients, name scoping), limits (20 chat_refs, 100 folders implied), and failure handling (35-second deadline, retry delays). An agent has enough to invoke it correctly and set expectations about what happens afterward.

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?

With 0% schema description coverage, the description must carry semantics and largely does: date_from selects older history, folder_ids handles larger selections, chat_refs is capped at 20 with equivalent links resolving once, and name scoping determines sharing between clients. The only gap is the name format constraint (lowercase pattern), which is left entirely to the schema's regex.

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 opening sentence gives a specific verb (Create) and a precisely qualified resource: a named, on-demand subscription with exactly one source selector. That framing immediately separates it from sibling operations like list_watches, delete_watch, or get_watch_changes, which manage or read subscriptions rather than create them. The tool's role is clear without opening the schema.

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 provides concrete selection guidance: 'Start now, or supply date_from for available older messages' and 'Use folders for larger selections' when chat_refs would exceed 20. It also explains the naming convention needed for independent consumers. It stops short of explicitly naming alternatives (e.g., list_watches to discover existing subscriptions, get_watch_changes to consume), so it is clear but not fully routing.

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