zia_list_network_svc_groups

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description merely says 'List', which is consistent with the annotation and doesn't contradict it. However, it adds no additional behavioral context such as potential large payloads, ordering, or any side effects beyond what the annotation implies. With annotations covering the safety profile, this is adequate but not rich.

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 a single sentence with no filler words, achieving maximum conciseness. It immediately conveys the action and resource without any unnecessary elaboration, which is ideal for a simple list operation.

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?

For a basic list tool, the description is adequate in that it states the core action. However, the search parameter is unexplained, and there is no mention of return format or defaults since no output schema exists. Given the presence of sibling tools and the query param's detailed explanation, the description itself is minimal but not severely incomplete, though a note about what 'search' does would improve completeness.

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?

The tool description does not add any parameter explanations; the query parameter has a detailed description in the schema itself, but the search parameter is completely undocumented in both schema and description. With schema description coverage at 50%, the description does not compensate for the unexplained 'search' parameter or add meaning beyond what the schema already provides for 'query'.

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 'List ZIA network service groups' clearly states a specific verb (list) and resource (network service groups) within the ZIA context. It distinguishes from siblings like zia_get_network_svc_group (which retrieves a single group) and zia_list_network_services (which lists services, not groups), making the purpose unambiguous.

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 offers no guidance on when to use this tool versus alternatives such as zia_get_network_svc_group for a specific group, or how search filters compare to query filtering. There is no mention of exclusions or conditions (e.g., 'use this for all groups, use get for specific'). The only us-related text appears in the query parameter schema description, not in the tool description.

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