metadata_user_upsert

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing about the critical upsert semantics: whether the metadata object merges with or replaces existing keys, whether nested values are shallow- or deep-merged, or whether it requires specific permissions. For an operation writing an arbitrary nested object, this is a real gap.

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 single short sentence is front-loaded and free of padding, but at five words it is under-specified rather than genuinely concise; it omits content an agent needs rather than trimming redundancy.

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 write tool taking an arbitrary nested metadata object, with no output schema and no parameter documentation anywhere, the description is far too thin. It should at minimum describe merge-vs-replace behavior and the expected metadata shape.

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% for both required parameters, and the description supplies no compensating detail. The 'metadata' parameter is a free-form nested object with additionalProperties, so an agent has no idea what keys are valid, what value types are expected, or whether partial updates are supported.

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 pair (update or create) and a specific resource (User Metadata), which cleanly separates it from metadata_node_upsert and metadata_user_get in the sibling list. It loses a point only because it does not clarify anything about scope or effect beyond the name-level restatement.

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?

There is no guidance on when to use upsert versus metadata_user_get, nor on what conditions trigger a create versus an update. The agent must infer everything from the tool name alone.

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