cork_get_compliance_events

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

No annotations are present, so the description carries the behavioral burden. It discloses default exclusions (resolved events excluded by default), how to include them, and the meaning of at_risk=true. It could mention pagination or ordering, but the key behavioral defaults are effectively surfaced.

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?

Three concise sentences: purpose, filter options, and default behavior. Every sentence adds useful information without redundancy or filler, and the most important usage details are 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 14-parameter tool with no output schema and no annotations, the description supplies the crucial behavioral defaults and cross-references for valid values and UUID sources. It is not exhaustive (no example output or sorting info), but it gives an agent enough to call the tool effectively.

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 coverage is high (86%), which sets the baseline at 3. The description adds value beyond the schema by tying event_type to a sibling tool, clarifying the resolved-event default behavior, and reinforcing the show_resolved requirement for resolved date filters. It doesn't describe every parameter, but the schema already handles those.

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?

Description uses a specific verb ('List') with a clear resource ('policy violations and risk events detected for a client's assets'), which distinguishes it from sibling tools like cork_get_compliance_event_types and cork_get_compliance_notification_settings. An agent immediately understands what this tool returns.

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?

Description gives concrete filtering guidance: use cork_get_compliance_event_types for valid event_type values, set at_risk=true for active risks, and set show_resolved=true to include resolved events. It doesn't explicitly mention when not to use this tool versus alternatives, but the read/list purpose is clear enough for routing.

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