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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description's real contribution is the all-or-nothing transaction contract and the validation/access-check gate — exactly the context an agent needs before firing a 2000-item write. It stops short of saying that upsert overwrites existing values or what error detail comes back on failure.

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 short sentences, each earning its place: scale, atomicity guarantee, and a use case. The most decision-relevant fact (all-or-nothing) is front-loaded.

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 destructive bulk mutation with no output schema and zero schema documentation, the description covers scale and failure behavior but omits overwrite/clear semantics, permission prerequisites, and what the caller gets back on partial validation failure.

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%, so the description carries the burden for the nested values array, yet it only restates the maxItems=2000 limit already encoded in the schema. Nothing explains entityType semantics (PROJECT/TASK/PROPOSAL), whether a null value clears a field, or how fieldId/entityId pairs are matched.

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+resource ("Upsert ... custom field values") plus a hard batch cap of 2000 and the atomic semantics. It is clearly distinguishable from sibling set_custom_field_value by the bulk framing, though it never names that single-value sibling 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?

"Useful for batch-populating fields on a set of imported tasks" gives one concrete usage scenario, but there is no explicit when-not guidance and no named alternative for the single-value case, so the agent must infer the boundary from the 2000-item cap.

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