zia_list_network_services

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds a behavioral detail about case-insensitive name matching, but does not disclose pagination, result limits, auth requirements, or rate limits. With annotations covering safety, the description provides minimal extra transparency.

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?

Two short, front-loaded sentences with no redundant information. Every word earns its place.

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?

No output schema and minimal parameter documentation. The description does not explain the return format, pagination, or authentication context. Given the tool's simplicity and the presence of sibling list tools, the description is adequate but incomplete for a full understanding.

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 low (25% - only 'query' described). The description adds meaning for the 'name' parameter (case-insensitive search), but ignores 'search' and 'protocol' parameters. Partially compensates for low coverage but does not fully explain all parameters.

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?

Clearly states it lists ZIA network services with verb 'List' and resource. The hint about case-insensitive name search adds value. Does not explicitly distinguish from the similar 'zia_list_network_svc_groups' sibling, but the resource specificity is clear.

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?

Only provides a parameter hint for 'name' but no guidance on when to use this tool versus alternatives (e.g., zia_get_network_service for a single service, or zia_list_network_svc_groups for groups). No when-not-to-use or prerequisites.

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