zia_list_web_dlp_rules

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description need not restate read-only behavior. However, the query parameter description adds valuable behavioral insight: it warns that field names are typically snake_case and advises calling once without query to inspect keys, preventing empty results from misguessing. This goes beyond annotations and helps agents understand tool output behavior.

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 declarative sentence, extremely concise and free of fluff. It states the tool's purpose efficiently, but is so brief that it could border on under-specification. Still, for conciseness and structure, it scores well because it wastes no words.

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?

With no output schema, the description does not indicate what fields the returned rules contain or any detail about the response format. It also fails to mention the existence of a 'lite' sibling that likely returns a reduced subset, leaving the agent without guidance on which list variant to use. The tool's complexity (optional filtering and potential naming pitfalls) is only hinted at in the schema, not the description.

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 the 'query' parameter has a detailed schema description, which explains JMESPath syntax, examples, and the snake_case caveat. The 'search' parameter has no description in the schema and the tool description does not clarify its purpose. Since coverage is exactly half, the description fails to compensate for the unexplained 'search' parameter, leaving agents to guess its semantics.

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 Web DLP rules' clearly states a specific verb ('List') and resource ('Web DLP rules') within the ZIA context. It distinguishes itself from siblings like zia_list_web_dlp_rules_lite (presumably a lighter variant) and zia_get_web_dlp_rule (get single rule) by its action and scope.

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 provides no guidance on when to use this tool versus alternatives. It does not mention the lite variant or the get single rule tool, nor any circumstances that would favor one over another. The only usage-related hint is embedded in the query parameter description, which is parameter-level rather than tool-level.

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