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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description credibly reinforces this by disclosing that removing lower_price also deletes its saved price target and that state should be re-read after a timeout or conflict before retrying. It adds real consequence and retry-hazard context beyond the annotations, though it could say more about the failure/conflict semantics themselves.

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?

Purpose is front-loaded and every sentence carries an instruction, consequence, or constraint, with no filler. It is dense to the point of being run-on in places, but nothing reads as padding.

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?

With three parameters, an output schema present, and destructive/idempotency annotations, the description covers the remaining gaps: operation choice, the side effect of removal, edit scope limits, user-consent requirement, and retry-after-conflict behavior. An agent has everything it needs to call this correctly.

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 67% and the description adds meaning on top of it: the effect of 'replace' (complete desired set, omitted criteria removed) and the destructive side effect of 'remove' on lower_price. The operation enum semantics overlap with the schema's own enum description, but the description still sharpens the intent behind each value.

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 first sentence gives a specific verb and resource – 'Edit criteria for an existing Hunt' – and pins the natural key ('its returned watch_id'). It also distinguishes the tool from the read-oriented sibling get_watch_updates, so an agent can place it without opening a schema.

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 states explicit when-to-use for each operation ('add to preserve existing criteria', 'remove to drop a lane', 'replace only for an explicit complete change'), names a when-not ('No size or budget editing is supported here'), and gives a precondition ('Never change a Hunt unless the user asks'). This is the full when/when-not/alternative triad.

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