Post collections update

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is known. The description adds only that this is a legacy v1 POST alias, leaving out what state gets replaced, whether the set is additive or replacing, and any auth/ownership requirements — meaningful gaps for a 'set' operation whose semantics are the main risk.

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?

A single short phrase with the distinguishing qualifier front-loaded; there is no filler. It is efficient, though brevity here shades into under-specification rather than deliberate economy.

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 legacy endpoint with 0% schema description coverage, an opaque json_body/form/params trio, and no output schema, the description leaves the agent without enough to build a correct call or predict the effect. The legacy marker is the only contextual aid provided.

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 description coverage is 0% across four parameters (form, params, cipher_id, json_body), including the lone required field cipher_id. The description mentions neither cipher_id nor how the collections payload is passed (json_body vs form/params), so it compensates for none of the schema's documentation gap.

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?

"Set collections" names a verb and resource, and "(legacy v1, POST alias)" distinguishes it from the PUT/collections2 siblings in the tool list. But it never says what a 'collection' update actually does here (cipher-to-collection membership? org collection config?), so an agent cannot confidently separate it from vaultwarden_put_collections_update or vaultwarden_post_collections2_update on function alone.

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 'legacy v1' tag implicitly signals this is a backward-compatible path and that a newer variant likely exists, which is useful routing information. However, it never states when to choose this legacy POST over the PUT alias or the v2 endpoint, nor any prerequisite like organization/cipher permission.

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