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

Annotations (readOnlyHint:false, destructiveHint:false) already indicate a write operation, and the description consistently says 'Create.' It adds extra behavioral context: the widget creates a visual annotation tied to cost movement, metadata.source is reserved/system-managed and must not be set by agents, and tag values should be discovered via list_tags rather than invented. This significantly enriches understanding of side effects and constraints.

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 front-loaded with a clear purpose, then logically progresses to usage guidance, parameter tips, and a compact example. Every sentence adds value: the widget guidance, tag discovery, metadata.source warning, and example all earn their place. While longer than average, it is appropriately sized for a tool with 8 parameters and nested objects.

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?

Given the tool's complexity (8 params, nested objects, no output schema), the description is remarkably complete. It covers when to use, how to construct a widget, tag conventions, metadata constraints, and provides a complete JSON example. It leaves little ambiguity about what the agent should provide in various scenarios, making it fully actionable.

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%, but the description goes far beyond baseline by providing a full worked example, explaining the widget object shares shape with the query tool, clarifying the use of tags with list_tags, and warning about metadata.source. This adds substantial semantic meaning to the parameters, especially for nested objects like widget and metadata.

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 'Create a new event to annotate a cost change,' which is a specific verb+resource+scope statement. It clearly distinguishes from sibling create tools like create_alert, create_dashboard, and create_report by focusing on cost-change annotation. The additional context about displaying events on cost charts reinforces the tool's unique 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?

Explicitly states when to use: 'Use this when the user wants to document why costs changed — e.g. a deployment, migration, pricing update, or business decision.' It also provides conditional guidance: 'Omit widget only for purely informational org-wide events,' and recommends calling list_tags to discover existing tags. This constitutes clear context and exclusions, well beyond a vague 'use this for events.'

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