List audit events

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

readOnlyHint=true already declares the safety profile, and the description adds useful context beyond it: results are workspace-scoped to the credential and returned newest-first, and the required timestamp establishes the read window rather than the query being open-ended. It does not mention pagination behavior or result volume, which keeps it short of a 5.

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 sentences, no filler. The scope and ordering lead, and the parameter-interaction rule follows in the second sentence where it is most actionable.

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?

An output schema exists so return values need no explanation, and all nine parameters are schema-documented. The description supplies scope, ordering, and filter-window semantics, but omits any pointer to sibling tools or a note on how the credential/account-id header interacts with the workspace scoping it mentions.

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 100%, so the baseline is 3. The description earns above baseline by explaining the semantic relationship between parameters - occurred_after defines the window and all other filters narrow within it, i.e. conjunctive filtering - which an agent cannot infer from the per-field descriptions alone.

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?

States a specific verb and resource (list the audit trail) plus scope ('for the workspace the credential resolves to'), ordering ('newest first'), and payload content ('who did what, to which resource, and what changed'). An agent can distinguish this from siblings like list_incident_events without opening either schema.

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?

Explains the mechanics of use: 'occurred_after' is required and sets the read window, while every other filter narrows within it. That is clear operating context, but the description never names an alternative tool or a when-not condition against siblings such as list_incident_events.

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