add_monthly

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

With no annotations provided, the description carries full burden. It explains the upsert operation, the required categories, and the post-call step. However, it does not explicitly state whether prior entries for the same period are replaced or merged, nor does it mention error handling or side effects.

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: a clear introductory sentence, followed by usage instructions and a detailed list of valid categories. It is front-loaded with purpose. However, the list of categories is lengthy, and the instructions could be slightly more concise without losing clarity.

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 does not mention the return value or response format of the tool, which is a gap given no output schema. It adequately covers the tool's process and valid inputs, but lacks information on what the agent should expect after the call (e.g., success/error feedback).

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?

The input schema covers period and date with descriptions, but the description adds critical context: valid categories and sub_types, the requirement to ask and confirm before calling, and the overall batch pattern. It compensates for the 50% schema coverage by detailing how to populate the balance and flow arrays.

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 this tool performs a batch upsert of both balance and flow entries for a single period, explicitly labeling it as the primary tool for month-end settlement. It distinguishes itself from sibling tools like add_balance and add_flow which handle individual entries.

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 explicit when-to-use triggers (e.g., '결산', 'month-end closing') and a step-by-step workflow: ask for categories, confirm numbers, call this tool once, then invoke report_settle. It also specifies valid category and sub_type strings, preventing misuse.

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