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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, non-open-world mutation, so the safety profile is covered. The description adds real value beyond that: the report-crediting consequence of adding an event and the founder-permission gate. It doesn't mention that repeat calls create duplicates despite idempotentHint=false, so it stops short of 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, front-loaded with the core action and safely sized, but the second sentence partly restates the first ('It adds data to the workspace' repeats 'Adds an event to the connected workspace'), and the parenthetical kind list duplicates the schema enum.

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 the description covers the mutation effect, permission prerequisite, date semantics and time zone an agent needs to call it correctly. Only the non-idempotent duplicate behavior is left to the annotations, which is a minor gap.

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 75%, just under the high threshold, and the schema already documents label, last_day and first_day. The description compensates by clarifying range semantics ('one day or a date range') and the workspace time zone, and by naming the kind/label/date trio, though it adds little for the undocumented enum field beyond repeating the options.

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 up front ('Adds an event to the connected workspace') and enumerates the event kinds, immediately contrasting the write action with the list_events read sibling. The purpose clause ('so sales around it aren't credited to creators in the next report') tells the agent exactly what the tool accomplishes, which a bare name cannot.

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?

Gives a clear precondition — 'meant for events the founder has confirmed (kind, dates and label)' and 'Needs the founder to have allowed marking events when connecting' — so the agent knows the context in which calling is appropriate. However, it names no alternative tool and states no explicit when-not conditions, so it falls short of a full 5.

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