bw_update_adso

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it honors that obligation: it states that remove_field also removes the field from the key if applicable, manage_keys replaces the complete list and allows an empty array, update_settings needs no infoobject_name, and adding a field without dimension falls into the catch-all group requiring an extra activation to move later. It also exposes the two-step lock+activate contract, which is a material behavioral side effect not evident from the schema.

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?

The text is front-loaded with a clear action list and each of the six actions is described in 1–2 focused lines. However, the description is verbose and recreates a lot of action detail as prose; it also interleaves related logical consequences (like dimension and activation cost) in a way that requires careful rereading. The length is justifiable for a 6-action tool with nested objects, but it could be tighter by moving purely recursive details such as field-group examples entirely into the schema.

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?

Despite having no output schema, this definition is not only lists the lock_handle result but also gives the exact sequence of lock_handle return and success. It documents prerequisites (info_objects for add_field, the need for DIM from bw_get_adso, transport requirement conditionality), and all nested parameter structures. For a n-ten-parameter tool with complex nested objects, there are no decision-critical blank spots left.

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?

Although the schema already covers 100% of the parameter names, the description adds non-mechanical meaning that is not in the schema: action-specific parameter dependencies, that an infoobject_name can be a comma-separated list, that key_fields=[] clears all keys, that unit_currency_field should be a field reference to a UNIT/CUKY field, and that a missing transport should only be supplied when the BW system requires it. It also explains subtle type behavior such as fixed-length/scale constraints for pure fields, so the agent can correctly compose calls without trying every combination.

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?

The description names a precise operation (updating an aDSO) and immediately breaks it into six specific, mutually exclusive actions, from adding/removing fields to updating settings and key management. This differentiates the tool from the sibling bw_get_adso and bw_create_adso by being the update/alter tool for aDSO resources. No ambiguity remains about what resource the tool operates on or what kinds of changes it can perform.

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?

Every action is given its own clear condition and prerequisite: infoobject_name is required for add_field/remove_field, fields array only for add_pure_field, settings only for update_settings, field_name/properties for update_field_properties, and key_fields for manage_keys. The description also explicitly warns about the cost of forgetting dimension (a second activation) and tells the caller to read the current group assignment from bw_get_adso. This gives an agent concrete when-to-use and when-to-omit guidance, plus the required follow-up activation sequence.

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