acr_update_network_rules

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

No annotations are provided, so the description must fully convey behavioral traits. It states 'Update' which implies mutation, but does not disclose side effects (e.g., whether existing rules are replaced or merged), required permissions, idempotency, or the impact of changing default_action. This is insufficient for a mutation tool.

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 short and front-loaded with the core purpose. The Args section is a bit redundant given the schema, but not overly verbose. Every sentence serves a purpose. Could be slightly tighter by removing the parameter list and relying on schema, but acceptable.

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 tool modifies network rules, yet the description only mentions default_action. There is no explanation of what network rules are, how to define IP rules or service endpoints, or the overall effect. The tool's behavior is underspecified, especially given that no output schema details are provided in the description (though one exists). An agent would lack sufficient context to use this tool correctly.

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 0%, so the description is the sole source. It adds minimal value: for resource_group and registry_name, it merely repeats the parameter names. For default_action, it clarifies it accepts 'Allow or Deny' and has a default of 'Allow', which is helpful. However, it does not explain how default_action interacts with existing rules or other parameters. Overall, adds some value but remains thin.

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 explicitly states 'Update network rules for a container registry', clearly indicating the action and resource. It distinguishes from sibling tools like acr_list_network_rules (read-only) and acr_update_registry (broader updates). However, it lacks specificity on what aspects of network rules are updated beyond default_action.

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?

No guidance on when to use this tool vs alternatives. There is no mention of prerequisites, when to use default_action Allow vs Deny, or how this tool relates to acr_list_network_rules or acr_update_registry. The agent receives no context for proper selection.

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