Get network security policy

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

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), it discloses the auth model (explicit networking:read, and that full/read defaults do NOT grant networking) and backend-enforced constraints (ownership, feature availability, service 2FA locks). Most valuably it pre-empts a real misreading: effective_policy.default_ingress/default_egress are implicit deny fallthrough and do not override default_policy=accept.

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?

Front-loaded with the return shape, then the semantic caveats, then the permission model; each sentence carries real information. Slightly dense and the 'or networking:manage for changes' clause is boilerplate that does not apply to a read-only tool, costing it a point.

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?

There is no output schema, so the description must explain the returned fields, and it does cover default_policy, group rules, generations, and the effective_policy semantics plus the auth/ownership preconditions. It stops short of enumerating the full response structure or error behavior, which for a high-complexity networking read is a minor remaining gap.

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 100% and both params are fully documented as exact lowercase UUIDs by owned resources, so the schema carries the load. The description adds no syntax, format, or relational detail about project_id or network_id, so the baseline 3 applies.

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 opening verb+resource statement names exactly what is read: default_policy, assigned group rules, and desired/applied policy generations, and it distinguishes policy generations from network and port generations. It never names a sibling tool, so an agent must infer the boundary against get_security_group_capabilities, list_network_security_groups, or set_network_default_security_policy on its own.

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 states a permission precondition (networking:read for reads, networking:manage for changes) but gives no when-to-use/when-not guidance and never names an alternative tool or the condition that would select one. The agent is left to infer that this is the read path for a network's security policy.

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