fields_update_definition

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

With no annotations, the description carries the full burden. It adds real value by disclosing a specific failure mode (409 cvrt_fields_json_shadowed: a read-only JSON file still overrides the DB copy), but it omits whether the operation overwrites irreversibly, what permissions are required, or what happens to unspecified fields.

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?

Two short, front-loaded sentences with no filler; the primary action leads and the error hint follows. The terseness borders on under-specification, but nothing is wasted.

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?

The schema fully documents the four required parameters and the definition object shape, so the inputs are covered. But for a destructive replacement tool with no annotations and no output schema, the description leaves mutation semantics and prerequisites unexplained.

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 100%, with all four parameters documented in the schema itself, including the 'definition' object's reference to fields_get_schema. The description adds nothing about parameter format or constraints, so the baseline 3 applies.

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 ('Replace a definition'), which is clear enough to distinguish from fields_create_definition and fields_delete_definition. However, it never names those siblings or clarifies that this is a full overwrite of an existing definition, so routing still requires opening the schema.

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 no when-to-use guidance and never references alternatives like fields_create_definition or fields_sync_definition. The 409 note is diagnostic context, not a usage condition, so the agent must infer all invocation criteria.

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