zpa_list_service_edges

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

The read-only behavior is already declared via readOnlyHint=true; the description reinforces it and adds useful context about health/status and individual-vs-group scope. However, it does not disclose pagination, result shape, or how search/query parameters affect behavior, so the added transparency is modest beyond the annotations.

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 zero filler. The first sentence states the action and scope, and the second provides a useful sibling disambiguation. No redundant text.

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 simple list tool, the description is mostly adequate and the sibling distinction is helpful. However, there is no output schema and no clarification of search/pagination/filtering semantics across the five optional parameters, leaving the agent with incomplete information for correct invocation.

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 only 20%, with only `query` documented. The description does not mention page, page_size, search, or microtenant_id, nor does it compensate for the low parameter documentation. It adds no value for parameter semantics beyond the schema.

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 uses a specific verb ('List') with a specific object ('individual ZPA Service Edges') and scopes it to 'health/status'. It explicitly distinguishes the tool from `zpa_list_service_edge_groups`, making its purpose unmistakable even among many sibling tools.

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 clearly indicates this tool targets individual Service Edges rather than the parent group resource, naming the exact sibling alternative. It stops short of broader when-to-use guidance (e.g., when to prefer zpa_get_service_edge for a single edge), so it earns a 4 rather than a 5.

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