watchlist_create

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

Adds real behavior beyond annotations: duplicate names are rejected, requests are guarded by durable idempotency, and the tool verifies new ID, entry order and account listing after writing. There is mild tension with idempotentHint=false, but that hint refers to natural idempotence while the key-based dedupe is described consistently with the schema's 'reuse only to reconcile the same request'.

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?

One compact sentence, front-loaded with the primary action and followed by the guarantee/side-effect clauses. No filler, though the semicolon chain packs three distinct ideas together and could be split for scanability.

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 mutating, open-world tool with no output schema, the description covers the write, the idempotency contract, the duplicate-name rejection and the post-write verification. It stops short of stating the tab/session prerequisite implied by target_id, which is the main remaining gap.

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 67% schema description coverage, the schema already explains name, entries format, target_id and expected_layout_id; the description adds only the implicit linkage of the idempotency key and the exact-order expectation for entries. The timeout_ms parameter is undocumented in both places and no parameter is named directly.

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 ('Create an independent named custom watchlist') plus the post-creation verification scope. The word 'independent' implicitly separates it from watchlist_add / watchlist_add_bulk, but no sibling is named explicitly.

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?

'Refuses duplicate names' and the idempotency requirement imply when the call will fail, giving some usage signal. However, it never tells the agent when to choose watchlist_create versus watchlist_import or watchlist_add, nor what prerequisites (an active tab from browser_list_tabs) are needed first.

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