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

The description discloses substantial behavior beyond the annotations: partial-update semantics ('omitted fields keep their current value'), a field precedence rule ('endDate wins over days'), and the side effect on existing data ('picks are kept; those no longer valid starts are just hidden'). For a mutation tool this is exactly the context an agent needs, and it does not contradict idempotentHint=true since repeated identical updates converge to the same state.

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 with zero waste. The most decision-relevant constraint ('Organiser only') is front-loaded, and every remaining clause conveys a distinct behavioral rule: field parity with create_event, patch semantics, precedence, and pick preservation. Nothing is repeated from the schema.

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?

The description covers the auth prerequisite, patch semantics, precedence rule, and the non-destructive handling of existing picks — the key things an agent needs for a mutation with no output schema. The main gap is that 'same fields and rules as create_event' makes full correctness dependent on the sibling tool's documentation, and error/response behavior is not mentioned, which is a minor omission for a settings-update tool.

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%, so the baseline is 3. The description adds genuine value above the schema: it clarifies that all fields except slug/adminKey are optional patch-style updates, and it resolves the endDate-vs-days ambiguity with an explicit precedence rule that the schema states less authoritatively. The 'same fields and rules as create_event' line also signals cross-tool consistency for parameter interpretation.

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 names a specific action ('change') and a specific resource ('any event settings'), and immediately qualifies it with 'Organiser only'. This cleanly separates it from create_event (creation), get_event (read-only), and vote_time/submit_availability (participant flows). The verb+resource+scope combination leaves no ambiguity about what the tool does.

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?

'Organiser only' is a clear usage gate that excludes participant-facing tools like submit_availability and vote_time, and 'same fields and rules as create_event' anchors the tool to the event-management flow. However, it doesn't explicitly name alternatives or spell out 'use create_event to create a new event', so some routing context is implied rather than stated.

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