Update School Event (Admin)

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

Annotations already set readOnlyHint=false and idempotentHint=true, but the description adds crucial behavioral context: partial update semantics (omitted fields keep current values), role authorization, and a mandatory user confirmation step. It also notes that event_id comes from list_school_events, which is an operational behavior. No contradiction with annotations; the description enhances transparency significantly.

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 front-loaded with the core semantic (partial update) in the first sentence, and each subsequent sentence delivers a distinct piece of action-guiding information: usage scenarios, alternative routing, role requirement, confirmation note, and ID source. No filler or redundant text; it earns every word.

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 has 10 parameters, a single required field, an enum for status, and an output schema, the description is remarkably complete. It covers the operation's semantics, usage boundaries, authorization, safety confirmation, and data sourcing. The output schema handles return value details, so no further return explanation is needed. Nothing an agent needs to correctly invoke this tool is missing.

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 value by explaining the global partial-update semantic (provided fields change, omitted fields retain values), which is not explicit in the schema. It also specifies the source of event_id. However, it does not elaborate on each parameter individually, relying on the schema for that, so a 4 is appropriate.

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 clearly states a specific verb and resource: 'Partially updates an existing school event'. It immediately differentiates from alternatives by explaining the partial update semantics and explicitly routing to cancel_school_event for outright cancellation. The usage examples (reschedules, capacity/price changes, status transitions) further clarify the tool's purpose.

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 explicitly states when to use the tool: 'Use for reschedules, capacity or price changes, and status transitions'. It also gives an explicit exclusion: 'Prefer cancel_school_event to cancel outright'. Additionally, it mentions role requirements (pac_cordinator or event_cordinator) and that it is a write operation requiring user confirmation, covering prerequisites and safety.

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