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

Adds side-effect information: when enough people want the same hotel in the same month, btw asks for a group rate. Also states the return value (count of others). Annotations already indicate idempotency and non-read-only, but the group-rate trigger is unique to the description.

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 no wasted words. Purpose is front-loaded, and the side-effect and return value are concisely stated.

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?

Covers core behavior, return value, and side effects. Lacks details about the note parameter and potential error conditions, but for a moderate tool with annotations and schema descriptions, it is largely sufficient.

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 80% with descriptions for hotel, month, nights, and email. The description confirms hotel can be name or link, month format YYYY-MM, nights optional, and email is the human's. It adds 'nights if known' which clarifies optionality, but does not explain the note parameter, which lacks schema description.

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?

Description states a specific verb (want) and resource (hotel), clearly distinguishing from siblings like want_gym and want_home. It explains the exact action: recording a hotel wish for a month and returning the count of other interested people.

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?

Provides clear context that this tool is for hotel stays, but does not explicitly name alternatives or when not to use it. With siblings like want, want_gym, want_home, an explicit exclusion would strengthen guidance.

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