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

The description asserts 'writes upsert on (entity_id, field_definition_id) so replaying a batch is idempotent', but the annotations declare idempotentHint=false. An agent reading both gets contradictory signals about whether repeated calls with identical arguments are safe, so the description actively undermines the structured hint.

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?

Purpose is front-loaded in the first clause, followed by the typed-column guidance, the shim alternative, the upsert note, and the scope requirement. It is a little long and restates some schema text, but every sentence conveys operational information.

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 7-parameter, 100%-documented, annotation-bearing write tool with no output schema, the description covers scope requirements, column selection, and the shim fallback well. It omits what the call returns (e.g. the created row ID), which is a minor gap given no output schema exists.

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 already 100%, so the schema carries the field-by-field documentation. The description still adds genuine meaning beyond it: the select constraint ('a select value must be one of the field's options'), the dispatch mechanics of the legacy `value` shim, and which typed column maps to which field_type.

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 and resource: create/upsert a custom field value for an entity, with the storage model spelled out (typed columns). It is clearly distinguishable from generic create_* siblings, but never distinguishes itself from the very close update_custom_field_value/delete_custom_field_value, and the '(upsert)' framing blurs the create-vs-update line.

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?

Provides a real prerequisite (requires custom_fields:write scope) and steers the caller toward the typed column over the legacy shim, which is useful context. It never states when to call this versus update_custom_field_value or list_custom_field_definitions, so tool-selection guidance remains implied rather than explicit.

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