pmg_when_group_update

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

With no annotations provided, the description fully shoulders the burden. It labels the operation as 'MUTATION (MEDIUM)' indicating a modest risk, details the dry-run default behavior, and clarifies that only non-None fields are sent to PMG while omitted fields retain current values. These details disclose key behavioral traits beyond the bare fact of updating, ensuring the agent understands the safe partial update 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?

The description is extremely concise: a single sentence followed by a bullet-like list of key facts. It front-loads the mutation category and operation, then succinctly adds critical details. Every sentence serves a purpose—no repetition or fluff.

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 the complexity (7 parameters, 14% schema coverage) and the presence of an output schema, the description covers the most essential aspects: mutation type, dry-run mode, required config, source of ID, and partial update semantics. It does not detail the output schema (unnecessary since it exists), but provides enough context for an agent to safely invoke the tool. The sibling list is extensive, but the tool's naming and description differentiate it adequately.

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 only 14% (only proximo_target has a schema description). The description compensates by explaining that ogroup is a numeric ID string from pmg_when_groups_list, and that confirm triggers execution. However, parameters like and_, info, name, and invert lack any additional explanation. The description states that only non-None fields are sent, which provides partial semantics, but the overall parameter understanding remains limited.

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 clearly states 'update a PMG RuleDB 'when' object group config', specifying the verb and resource. It also includes the API path (PUT /config/ruledb/when/{ogroup}/config) and distinguishes from sibling tools like pmg_when_group_create, pmg_when_group_delete, etc., by focusing on update functionality.

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 explains that it performs a dry-run by default and requires confirm=True to execute, guiding the agent on invocation. It also mentions the need for PROXIMO_PMG_* config and where to get the ogroup parameter (from pmg_when_groups_list). However, it does not explicitly contrast with alternatives like pmg_when_group_get or pmg_when_group_objects, which could be helpful for usage decisions.

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