list_events

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

readOnlyHint=true already establishes this is a safe read. The description adds the useful fact that ids are auto-minted and that each action demands specific extra fields, but it says nothing about this tool's own operational behavior — output shape, result size, caching, or whether the catalog is site-specific — so it adds only modest context beyond the annotation.

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 core purpose is front-loaded in the first clause, and the attach mechanism plus example follow in the same compact block. It is dense with parenthetical '…' enumerations, which cost a little readability but every element (triggers, actions, required fields, attach path, example) earns its place.

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 zero-parameter, read-only catalog tool with no output schema, the description carries the return-content burden well: it says the listing covers triggers and actions with the exact extra fields each action needs. It would be complete if it clarified the exact response format (flat list vs. grouped by trigger) given there is no output schema to fall back on.

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?

With zero parameters the baseline is 4, and the description usefully compensates by explaining the shape of the event objects referenced elsewhere (action plus required extra fields, trigger eventName values). That is meaningful semantics even though it describes the payload of new_element/new_section rather than a parameter of this tool.

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+resource — 'List every interaction EVENT you can attach to a node' — and immediately enumerates what those events are (triggers and actions), so an agent knows exactly what it gets back. It implicitly separates itself from the many sibling list_* tools by scoping to page-element event catalogs, though it never names a sibling alternative explicitly.

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?

It states how the results are consumed — attach via new_element/new_section opts.events — and gives a concrete call example (opts.events=[{ action:'add_to_cart', open_page:'cart' }]), which tells the agent when this catalog is relevant. It stops short of an explicit when-not-to-use or a 'call this before X' instruction, so it is strong context rather than full routing guidance.

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