transferGift

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

With no annotations, the description carries the full behavioral burden. It adds the permission requirement and return value, which is meaningful context. However, it does not disclose the consequential nature of the operation (the original owner loses the gift) or the star_count constraint behavior (paid transfers cannot be sold and must match the original amount) — though part of that lives in the schema, the irreversible ownership change is left unstated.

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, zero filler: the core action is front-loaded first, the permission prerequisite second, and the return contract third. Every sentence earns its place, and the most decision-relevant information appears immediately.

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 description covers the essential elements an agent needs: what the tool does, its permission requirement, and its return contract ('Returns True on success'), which matters since no output schema exists. The star_count constraints are already fully documented in the schema, so the description need not repeat them. A slightly fuller warning about side effects would push this to a 5, but for a 4-parameter scalar tool this is largely adequate.

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 100%, so the baseline is 3. All four parameters are already documented in the schema, including the nuanced star_count behavior. The description adds no param-specific meaning beyond the schema — it does not, for example, clarify how new_owner_chat_id relates to the transfer semantics beyond what the schema states.

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 and resource: 'Transfers an owned unique gift to another user.' The phrase 'owned unique gift' clearly distinguishes this from sendGift (gifting a new/unowned item) and transferBusinessAccountStars (transferring stars, not gifts). However, it never explicitly names or contrasts any sibling, so differentiation is left to inference rather than stated.

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 provides one concrete usage condition: 'Requires the can_transfer_and_upgrade_gifts business bot right,' which communicates a prerequisite and implies this is a business-account operation. But it offers no guidance on when to choose transferGift over related siblings like sendGift or convertGiftToStars, and no when-not-to-use or alternative routing.

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