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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description focuses on additional behavior: events are returned sorted by date descending, include metadata and widgetEvents, and widgetEventId can be used with update_event. This adds meaningful context beyond the annotations without contradicting them.

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 opens with the core action, then gives a use case, return details, and two illustrative examples. Every sentence earns its place, though the examples add length. It is appropriately front-loaded and structured for quick comprehension.

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 5 parameters and no output schema, the description covers the return format (sorted, metadata, widgetEvents), parameter nuances via examples, and the relationship to update_event. It omits pagination/limits, but for a list tool with this scope, the description is largely 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 coverage is 100% with clear descriptions for each parameter. The description adds value through examples showing realistic parameter combinations (e.g., category 'TECHNICAL' for deployments) and clarifies the functional intent of from/to and category. This goes beyond the schema's basic property descriptions.

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 states a specific verb-resource pair ('List events') with a clear scope ('deployments, business changes, provider updates') and date range. It distinguishes itself from siblings like create_event and update_event by focusing on listing existing events, and even references update_event for further actions.

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 explicit usage guidance: 'Use this to correlate cost changes with real-world events' and 'After query you may optionally call this'. It also provides concrete examples with parameter mappings. It does not explicitly say when NOT to use it, but the workflow context and sibling reference (update_event) imply alternatives.

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