Get sellable quantity

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond that: shares tied up in open sell orders or unsettled are excluded, exceeding it yields a 422 error, and KR quantities are whole shares while US quantities can be fractional. No contradiction with annotations.

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 core purpose is front-loaded and the explanation is efficient. Each sentence adds useful information about behavior, errors, or return values. The Args section is slightly redundant with the input schema, but the overall length is reasonable for a tool with this much behavioral nuance.

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 main use case, the key caveat (unsettled/open-order shares), the failure mode, the return shape, and the KR/US fractional distinction. Combined with full schema coverage and an output schema, there are no meaningful gaps an agent would need to guess about.

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 schema fully documents all three parameters. The description's Args list mostly restates what the schema already says, including the optional behavior of account_seq and the default of response_format. It adds no significant new parameter-level meaning beyond the schema.

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 names a specific verb and resource: 'Get how many shares of one symbol can be sold right now.' It also distinguishes itself from holdings by explaining that the sellable quantity can be lower than the holding quantity when shares are tied up or unsettled. This makes it easy for an agent to tell this tool apart from siblings like tossinvest_get_holdings.

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 gives clear usage context: 'Check it before selling' and warns that exceeding the quantity fails with 422 insufficient-sellable-quantity. It also clarifies that this is not the same as holding quantity. It does not explicitly name an alternative tool, but the situational guidance is strong enough for an agent to decide when to call it.

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