zia_list_rule_labels

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

Annotations already declare readOnlyHint=true, so the description does not need to restate that. However, it adds no additional behavioral context (e.g., return format, pagination, or limitations). The description is a bare statement and does not contradict 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?

The description is a single sentence, making it extremely concise and easy to parse. However, it is almost terse to the point of under-specification, but it does not waste words and is appropriately front-loaded.

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 list tool with 2 parameters (one half-documented in schema), no output schema, and only a sentence description, the agent lacks critical context about what 'rule labels' are, what the response structure looks like, or how the 'search' parameter behaves. The description does not suffice to guide correct invocation beyond the simplest case.

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 50%—only 'query' has a detailed schema description, while 'search' is undocumented. The tool description itself says nothing about parameters, so it fails to compensate for the missing 'search' semantics. The detailed query description is in the schema, not the tool description, so credit is limited.

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 clearly states the verb 'List' and the resource 'ZIA rule labels', which distinguishes it from the sibling 'zia_get_rule_label' (which fetches a single label). It is specific and 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 implies usage by listing rule labels but does not explicitly state when to prefer this over alternatives (e.g., zia_get_rule_label for a single label) or mention any exclusions. It provides no context on filters or when to use the 'search' parameter.

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