get_markets_margin_interest

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

Adds significant behavioral context beyond annotations: default summary mode vs full data with detail=True, and that any filter parameter triggers full data. Annotations already declare read-only/idempotent, so the bar is lower; this description adds useful return-shape behavior.

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?

Well-structured with purpose line, usage guidance, behavior explanation, supported plans, and args list. Slightly dense but every sentence is informative; the length is justified by the tool's complexity.

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 read-only data tool with five optional parameters and an output schema, the description covers plan prerequisites, default vs detailed output, parameter formats, and the relevant sibling alternative. No significant gaps.

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 fully documents each parameter in Args: code (5-digit example), date formats, date_from/to, and detailed effect of detail flag. This entirely compensates for the schema gap.

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?

Clearly identifies the tool as returning per-stock margin balance (買残・売残・貸借倍率) with a specific resource. Distinguishes from sibling get_markets_margin_alert by stating that tool is for margin trading restrictions.

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 states when to use: 'Use for 信用残...' and provides alternative: 'For margin trading restrictions, use get_markets_margin_alert instead.' Also mentions 'Standard+ only' plan requirement.

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