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

The annotations already declare destructiveHint=true, and the description usefully adds the unlock_shareflo gating requirement, which is real behavioral context beyond the structured fields. However, it never explains what the operation alters or why a creation is flagged destructive, nor what matters about the unlocked session, so the added value is modest.

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, zero filler. The core purpose leads and the prerequisite follows immediately, so both facts an agent needs are front-loaded and no sentence is redundant.

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 an 11-parameter mutation with no output schema, the description covers purpose and the unlock prerequisite but omits what is returned (e.g. the new instrument identifier) and any hint about the destructive flag's implication. Combined with 100% schema coverage the gaps are not fatal, but they are visible for a create operation.

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% with 11 documented parameters, 3 enums, and conditional mandatory rules (nominal_value/currency for Shares, exercise_price/currency/underlying_share_class for Options), so the schema carries the semantics. The description contributes nothing parameter-specific beyond the subtype vocabulary, which is the correct baseline of 3.

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 ('Creates') and resource ('a new instrument') and scopes it ('for the company'), then enumerates the concrete subtypes (share class, option class, or other) that mirror the instrument_type enum. This clearly separates it from sibling creators like create_holding and create_stakeholder without naming them.

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?

Gives an explicit prerequisite: unlock_shareflo must have been called first, which directly ties it to a named sibling tool and prevents a failed invocation. It stops short of stating when NOT to use it or naming alternatives such as get_instruments for inspection, so it falls short of the full when/when-not bar.

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