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

The description goes well beyond the annotations by disclosing that earlier approvals are replaced, that an empty list clears approvals, that a valid identity with a saved start is required, and that invalid keys produce an error listing the current options. It also clarifies that the tool is rejected after the organiser decides. These behavioral details add substantial value and do not contradict the annotations; the idempotentHint aligns with the replace/set semantics.

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 dense but every sentence earns its place: it front-loads the core behavior, then adds constraints, error behavior, a rejection condition, and a concrete example. Nothing is redundant or filler.

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 and lack of an output schema, the description covers all invocation-critical aspects: required identity linkage, accepted key source, clearing behavior, rejection after decision, and the shorthand. An agent has enough context to call the tool correctly without additional lookups.

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 extra meaning by explaining that `identity` must be the same one used in submit_availability, that accepted starts come from get_event.voteOptions, and that `start` is shorthand for a single-item `starts`. The included example also clarifies how slug, identity, and starts fit together.

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 states a specific verb and resource: 'set every start one person accepts', and frames it as 'approval voting', distinguishing it from the initial availability submission tool. It also references get_event.voteOptions and the organiser's decision, which separates it from decide_time. This is specific enough for an agent to select it correctly among the siblings.

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?

The description gives clear usage context: the voter must have already saved at least one start via submit_availability, only keys from get_event.voteOptions are valid, and the tool is rejected once the organiser has decided. It also explains the effect of an empty list, which is essential for using the tool correctly. This effectively communicates when to use the tool and when not to.

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