Edit watchlist

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine context the annotations cannot: that add/remove/rename can be batched into a single call and that the tool reports back what changed, which matters because there is no output schema.

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?

Two short sentences with no filler: the first front-loads the full set of operations, the second covers return behavior and the read alternative. Every clause earns its place.

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 5-parameter mutation tool with 20% schema coverage and no output schema, the description leaves real gaps: the required id, the role of market in resolving ticker symbols, and the 100-item cap on add/remove are all unmentioned. It does cover the return shape adequately.

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 only 20%, so the description has to carry more weight. It maps its prose onto the name, add and remove parameters, but leaves the required 'id' undocumented and never explains how 'market' governs ticker resolution for add/remove.

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 gives a concrete verb plus resource (rename a watchlist, add/remove instruments) and spells out the three sub-operations an 'edit' can perform, which is more than the title alone conveys. It also names get_watchlist as the read counterpart, though it stays silent about the adjacent create_watchlist/delete_watchlist 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?

It points the agent at get_watchlist for reading the resulting list, which is a usable post-call routing hint. However there is no guidance on when to edit vs. create or delete a watchlist, nor on prerequisites such as needing a valid watchlist id first.

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