Update custom field

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

Annotations already indicate this is a mutating, non-idempotent operation. The description adds meaningful behavioral context by explicitly stating that data_type cannot be changed in Paperless, preventing an agent from attempting an unsupported modification.

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?

One concise sentence that front-loads the primary actions, gives an example, and states a key limitation. Every part adds value with no redundant filler.

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 description plus schema provide enough for an agent to make a correct update call: required id, optional name and extra_data, and a clear restriction on data_type. It does not describe the return value, but there is no output schema and this is a simple mutation 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 0%, so the description must carry the meaning. It explains that name is the new field name and extra_data supports modifications like adding select options. The id parameter is not explicitly described, though it is clearly the identifier of the custom field being updated.

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 specific operations: renaming a custom field or adjusting its extra_data, with a concrete example. This clearly identifies the resource and action, and distinguishes it from create/get/delete custom field siblings.

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?

The description makes clear this tool is for modifying an existing custom field's name or extra_data. It also warns that data_type changes are not supported, which is a useful when-not constraint, though it does not explicitly point to alternatives like create_custom_field for new fields.

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