cloud_insts_assign_secgrp

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

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the effect of NULL port_id for multiple groups, and the resolution logic for project and region identifiers. However, it lacks details on idempotency, error handling, or response behavior. Still, the described nuances add significant value beyond the basic action.

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 structured with a brief main statement, a usage tip, a parameter list, and a separate note. It is front-loaded with the core action, but the parameter list is somewhat verbose, and the note on project/region resolution is lengthy but necessary. A more concise formatting (e.g., bullet points for usage guidelines) would improve readability.

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 9 parameters, 3 required, no output schema, and no annotations, the description covers the main action, parameter usage, and important resolution details. However, it does not describe the return value, error conditions, or idempotency. For a tool with many generic extra_* parameters, the description is adequate but lacks some behavioral context to be fully complete.

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?

With 0% schema coverage, the description must compensate. It explains key parameters like name ('applies to all ports') and ports_security_group_names ('Port security groups mapping'), and provides a detailed note on project_id and region_id resolution. However, generic parameters (extra_headers, etc.) are only listed without further explanation, and the schema's PortsSecurityGroupName structure is not described in prose. The description adds moderate semantic value but is not exhaustive.

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 the tool's purpose: 'Assign the security group to the server.' It uses a specific verb ('Assign') and resource ('security group to server'), and the sibling tool 'cloud_insts_unassign_secgrp' provides a clear opposite, aiding differentiation.

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 provides explicit usage guidance, such as using NULL for port_id to assign multiple security groups to all ports, and detailed instructions for resolving project_id and region_id. While it doesn't explicitly contrast with sibling tools, the context implies when to use (assigning security groups) vs unassigning. The guidance is actionable and clear.

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