List network attachment candidates

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context: the port_intent_ready prerequisite, pagination mechanics (follow next_cursor via after while candidates_has_more), and backend-enforced ownership, feature availability and 2FA locks. The phrase 'networking:manage for changes' sits awkwardly against readOnlyHint=true, but it reads as permission boilerplate rather than a functional claim of mutation.

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?

It is a single dense run-on paragraph packing prerequisites, pagination, routing, permissions and enforcement into stacked clauses. Nothing is clearly wasted, but the lack of front-loaded purpose and the packed structure make it harder to parse than it needs to be.

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?

With no output schema, the description steps in to name return concepts (attachment_mode, reason_code, candidates_has_more, next_cursor) and explains prerequisites and enforcement. It never fully describes what a candidate record contains, so it is strong but not exhaustive for a list 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 only 33% (network_id alone), so the description must compensate, and it does: service_id 'selects one owned service' and after is tied to following next_cursor. This adds meaning for both undocumented parameters, though it omits format/syntax details the schema also lacks.

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 identifies a specific operation on a specific resource: checking each existing service's attachment eligibility and attachment_mode for a network where port_intent_ready=true. It is clear what the tool returns at a per-service level, though it opens with a precondition rather than a plain statement of purpose and provides no explicit sibling 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?

It gives real routing guidance: use the per-service result and reason_code for existing-VM attachment, not new-server order_availability, and 'Do not attach a service the backend marks ineligible.' The scope condition (port_intent_ready=true) is stated. It stops short of naming a concrete alternative tool for the new-server case, keeping it below 5.

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