proofpoint_events_list

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that events are filtered to those where Proofpoint detected and acted on threats, but it does not disclose default time ranges, pagination, response structure, or other behavioral traits. The absence of any safety hints (e.g., read-only) is notable for a tool that lists events, yet the description offers no reassurance or caveats.

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 two sentences, front-loaded with the primary action, and contains no redundant or irrelevant information. Every word contributes to the overall purpose, making it highly concise and well-structured.

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?

The tool has moderate complexity with 5 optional parameters and no output schema or annotations. The description explains the core functionality and the nature of returned events, but it omits details about default behavior (e.g., time window), result format, or how this relates to sibling list tools. Given the absence of structured hints, a more complete description would mention such context, so it is only minimally complete.

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 100%, so the baseline is 3. The description adds no parameter-specific semantics beyond what the schema already provides; it merely echoes the threat types in prose. Since the schema already documents all parameters with enums and descriptions, the description does not need to compensate, but it also does not enhance understanding.

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 action ('List') and the resource ('spam, phishing, and malware detection events'), and adds context that it returns events where Proofpoint acted on threats. This distinguishes it from detail/stats tools, though it does not explicitly differentiate from sibling event tools like proofpoint_events_get_details or get_stats. The omission of 'impostor' from the threat types is a minor gap but does not obscure the primary purpose.

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?

No guidance is provided on when to use this tool vs. alternatives. There is no mention of using proofpoint_events_get_details for single-event details or get_stats for aggregated metrics, nor any exclusions. The description merely states what it does, leaving the agent to infer applicability from the name alone.

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