fields_update_organization_field

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

With no annotations, description carries full burden. It discloses key behaviors: field_type cannot be changed, options represent the full set after update with id preservation semantics, and lists common modifications. Doesn't mention side effects on existing data or authorization, but adequately covers the tool's mutational behavior.

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?

Concise and well-structured: brief purpose statement, a note with critical behavior, and bullet-pointed common use cases. Front-loaded with essential information, no redundant sentences.

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?

Given no output schema, description covers core aspects: field_type constraint, options handling, and common use cases. Lacks return value description but is sufficient for selection and basic invocation. Adequately complete for an update tool.

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 100%, baseline 3. Description adds value beyond schema by explaining the options replacement behavior and providing common use cases that inform parameter usage. The note about including existing option ids to preserve them is not in the schema, enhancing semantic clarity.

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?

Description clearly states 'Update an existing custom organization field' with specific verb and resource. Lists common use cases such as renaming a field, adding/removing options, and toggling visibility, which further clarifies purpose and distinguishes it from sibling tools like fields_create_organization_field.

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 guidance on when to use (updating existing fields) and important constraints like field_type immutability. Implicitly distinguishes from create/delete siblings through common use cases, but lacks explicit 'when not to use' or direct alternative references.

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