Move the voting deadline

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

Annotations only say readOnly=false and destructive=false; the description adds that the override is one-off, that extend_hours is measured from the current deadline, and that future schedule changes via update_recipe_preferences re-sync the week. It doesn't disclose behavior when both closes_at and extend_hours are passed or how to revert, so not a 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 focused sentences, with the core action front-loaded and the schedule relationship in the second sentence. No redundant restatement of the name or annotation fields.

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 a mutating tool with optional params and no required fields, the description should clarify the default week and parameter exclusivity; it doesn't. However, it does provide the key schedule context and output schema exists, so it is adequate but not complete.

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?

Description provides semantics for closes_at ('ISO timestamp') and extend_hours ('from the current deadline') beyond the schema, but covers only 2 of 3 params. week_id has no description in the schema or prose, and the relationship between closes_at and extend_hours isn't stated; at 33% schema coverage this gap matters.

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 operation ('one-off override') on a specific resource ('when the current ballot closes') and clarifies the two input modes. It also distinguishes itself from the normal scheduling path by naming update_recipe_preferences, so it is not confused with schedule changes.

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?

'One-off' tells the agent this is for temporary/current-week cases; the second sentence explicitly names the normal source of the deadline and the sibling tool (update_recipe_preferences) to use when changing the schedule. This effectively gives a when/when-not pairing.

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