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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context: the conditional refund logic, the requirement of a cancel reason for analytics, and the edge case where an SMS arriving during cancel keeps credits charged and returns the code. This goes beyond the annotations and helps the agent anticipate outcomes.

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?

Three sentences with no filler. The core action and refund condition are front-loaded, the reason requirement is stated, and the edge case is given in one compact sentence. Every sentence earns its place.

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?

The tool has an output schema, so return values need not be described. The description covers the main behavior, the reason requirement, and the race condition with SMS arrival. It does not mention prerequisites like having an active rental or authentication, but those are implied by the tool's domain and sibling context. Slightly more detail on what 'code is returned' means could push it to 5.

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 description coverage is 0%, so the description must compensate. It explains the purpose of 'reason' (for analytics) and lists its enum values, which the schema already provides but the description reinforces. It does not explain 'rentalId' or 'reasonNote' beyond what the schema shows, but the tool name and context make rentalId self-evident, and reasonNote is optional. The description adds meaningful semantics for the key parameter.

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 ('Cancel'), a resource ('an active rental'), and the key side effect ('refund credits when no SMS has arrived'). It clearly distinguishes this from sibling tools like ucode_sms_get_code or ucode_sms_refund_expired by focusing on cancellation with refund semantics.

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 implies when to use this tool: when an active rental needs to be cancelled and no SMS has arrived. It also provides the required reason enum values, which guides correct invocation. However, it does not explicitly state when NOT to use it or name alternative tools (e.g., ucode_sms_refund_expired for expired rentals), so it falls short of a 5.

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