unifi_protect_list_events

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

Annotations only declare readOnlyHint=true; the description carries the behavioral burden and succeeds. It discloses that result warnings must be checked before reporting counts, that a disabled detector returns zero matches rather than proving nothing happened, that times follow the console's local clock, and that results include the camera name to avoid a second lookup. This is exactly the kind of non-obvious behavior an agent needs to interpret results correctly.

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 longer than average but every sentence earns its place: purpose, use case, result-field convenience, timezone nuance, warning behavior, and filtering advice. It is front-loaded with the core action and structured so the most critical warning is set off in caps. The busy-system point is slightly redundant with the limit parameter description but still reinforces the needed behavior.

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 explains what results carry and warns about the most failure-prone interpretation, zero matches versus disabled detection. It also addresses timezone semantics and camera-name availability. The schema covers parameter detail, so an agent has enough context to invoke the tool and interpret its result correctly.

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?

The schema already covers all parameters with detailed descriptions, enums, defaults, and constraints, so the baseline is 3. The description's mention of types, smartDetectTypes, and cameraIds adds strategic emphasis but no new parameter semantics beyond what the schema provides.

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 opens with a specific verb and resource: 'Search recorded events over any time range', then enumerates the event categories covered. It clearly positions this as the list/search tool for recorded events, distinguishing it from sibling tools like get_event, get_event_thumbnail, and export_video. The example use case 'what happened at the front door last night' removes any ambiguity about the tool's role.

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 gives a concrete use case and tells the agent to narrow with types, smartDetectTypes, and cameraIds, and to check warnings before reporting counts. It does not explicitly state when to prefer alternatives such as get_event or unifi_protect_get_event_thumbnail, but the context is clear enough for an agent to select this tool for broad historical queries.

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