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

The annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description only needs to add context. It contributes a short 'Effects: event recorded as planned, with its source' line and the useful behavioral fact that source will be read back by a human deciding whether to attend. It does not address what happens on duplicate events despite idempotentHint=false, nor on an unknown account_id.

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 purpose is front-loaded correctly, but the body is roughly 250 words for a simple record-creation call, and the CRM-20 warning is restated three times with a narrative illustration ('Reading one off by position is how a first approach ends...') plus a closing aphorism ('An event nobody can trace is a diary entry, not a record'). The anti-invention rule earns its place; the second and third restatements of it do not.

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?

No output schema exists, so the description should signal what happens on success, and 'Effects: event recorded as planned, with its source' does that at a minimal level. With 100% schema coverage and full annotations, the remaining gaps are error/duplicate behavior and whether an event id is returned, which are modest but real for a 10-parameter mutation.

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 description coverage is 100%, so the baseline is 3, but the description adds real guidance beyond the schema: the format contract for source ('a URL when you found it, or "told by <name> on <date>"'), the account_id-vs-contact_id decision rule, and the intent of the note field. The date provenance rule is also reinforced in prose rather than left to the schema alone.

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 opening sentence gives a specific verb and resource ('Put something that is going to happen on an account') plus concrete examples (workshop, call, deadline), which clearly signals a scheduled-future event rather than a past-tense activity log. It never names the adjacent siblings (crm_log_activity, crm_update_event, crm_attend_event), so the distinction stays implicit.

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 gives explicit when-to-use rules for contact_id ('when the event is with, or run by, a specific person') versus account-only for a public workshop, and an explicit when-NOT-to-create rule: 'If the source does not pin the date, there is no event; tell your human what you found and where.' That is both an exclusion and a fallback action.

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