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

Annotations carry only a title and destructiveHint=false, so the description bears the burden and does so thoroughly: it discloses that the new holding uses tax scheme None, that omitting price means a free transfer, that omitting vesting means no vesting, that partial transfers require vesting to be stopped, and that nothing changes until confirm_action. This is well beyond what the thin annotations provide.

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?

The description is long but front-loaded with the core operation and then stacks prerequisites and defaults, with virtually no filler. Each sentence carries distinct information, though the density of constraints makes it slightly heavy to parse in one pass.

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?

For a 13-parameter mutation-style tool with no output schema and minimal annotations, the description covers the proposal-only behavior, all key prerequisites, recipient existence, partial-transfer constraints, and default semantics. An agent has everything needed to invoke it correctly without opening other schemas.

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 100%, so the schema already documents all 13 parameters and the baseline is 3. The description still adds meaningful semantics the schema lacks: omission of price_per_share implies a free transfer and omission of vesting implies no vesting, plus the cliff/vesting_period/vesting_start_date interplay and the take_from conditional.

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 verb (proposes transferring) plus the resource (shares), the source (one holding), the destination (another stakeholder in the same company), and the resulting state change (recipient gets a new holding, transferor's is reduced). It is clearly distinguishable from sibling tools like create_stakeholder and stop_vesting, which it names by function.

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?

Explicitly routes the agent to alternatives and states prerequisites: create the recipient with create_stakeholder first, call stop_vesting before a partial transfer, call unlock_shareflo beforehand, and use confirm_action to actually apply. It also rules out a whole class of operation (options can't be transferred), which is exactly the kind of when-not guidance that prevents misfires.

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