update_import_metadata

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

Annotations already declare non-read-only, non-destructive, open-world, so the description is free to add what they cannot: that prior state is snapshotted (giving an undo path), that video bytes are untouched, that the operation is scoped to a single item, and critically that it is replace-not-merge semantics ("Omitted supported fields are cleared"). Missing are failure modes such as revision conflicts and any auth/permission requirement.

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?

Three sentences, front-loaded with the verb and the key replace constraint, with no filler. "No arbitrary paths or item IDs" is compressed to the point of being cryptic, costing a little readability for its brevity.

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?

It covers the destructive-ness story and the clearing behavior well for a nested-object mutation with no output schema. It falls short on concurrency (what happens when expectedRevision does not match), on what "refresh/verify" actually reports back, and on any prerequisite that openWorldHint implies.

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 required parameters, so the description carries the burden — and it only partially does. It explains the replace semantics of the nested metadata object, which is genuinely valuable, but expectedRevision (the optimistic-concurrency token accepting "initial" or a revision UUID) and profileId are never mentioned, leaving the two most non-obvious parameters undocumented anywhere.

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 uses a precise verb+resource ("Replace ... metadata fields") and constrains it to "your own completed upload," so the agent knows this is a mutation on an existing job's metadata rather than a read or a re-import. It does not name the near-identical siblings (restore_import_metadata, refresh_import_metadata), so the distinction between replace/restore/refresh must be inferred.

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?

"for your own completed upload" and "No arbitrary paths or item IDs" give preconditions, implying this only works on jobs you own and already finished. But no sentence says when to pick this over restore_import_metadata or refresh_import_metadata, which are the obvious alternatives an agent will be choosing between.

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