calculate_leave_days

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

No annotations are provided, so the description carries full burden. It describes calling an internal API, performing balance checks per leave type, and returning a result. However, it does not disclose potential destructive effects, side effects, or error handling (e.g., insufficient balance).

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 well-structured with Args and Returns sections, front-loading the purpose. It is clear and informative, though slightly verbose with internal API references. Every sentence adds value.

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?

Given the high parameter count and lack of schema descriptions, the description covers each parameter adequately. It mentions the return type CalcDaysResult and its contents. Missing details like error conditions or constraints (e.g., date format) but still sufficient for an agent.

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%, but the description provides detailed explanations for all 10 parameters, including their purpose (e.g., leave_type for balance check, avlb_annl_leave from init_leave_flow) and defaults (start_time_code default AM). This adds significant value 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 clearly states the tool calculates actual leave days and validates leave balance, using specific verbs ('计算', '校验') and resources ('休假天数', '假期余额'). It distinguishes from siblings like init_leave_flow and submit_leave_application by focusing on the calculation step.

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 context on when to use (after init_leave_flow, which provides balances) and for which leave types balance checks are performed. It does not explicitly state when not to use or direct to alternatives, but the flow is implied.

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