calculate_sip_returns

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the output fields (invested amount, units, current value, absolute return, XIRR), the end_date default, and accepted date formats, but omits whether the call makes a live data fetch, what happens for an invalid or delisted scheme_code, and whether the operation is side-effect free.

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?

Three short lines, front-loaded with the purpose, then the return values, then the operative defaults and formats. No filler and nothing important buried at the end.

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?

An output schema exists, so explaining return values is optional (and here slightly redundant); the real gaps are elsewhere — the provenance of scheme_code, error behavior on missing NAV data, and how the monthly installment dates roll from start_date are all unstated. Adequate but not sufficient for a numeric simulation tool with zero annotation and zero schema-doc support.

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 all four parameters are undocumented in the schema. The description compensates for end_date (defaults to today) and start_date (accepted formats) and implies monthly_amount via 'monthly SIP', but leaves scheme_code completely unexplained — an agent is not told it must come from search_schemes.

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 and resource — 'Simulate a monthly SIP in a scheme using its real NAV history' — which is concrete enough for an agent to act on. It implicitly separates itself from the forward-looking 'project_sip' by emphasizing real NAV history, but never names that sibling, so full differentiation is left to inference.

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?

Usage is only implied: 'real NAV history' hints this is the historical/backtest counterpart to project_sip, but the description never states when to pick this over project_sip, calculate_lumpsum_value, or calculate_xirr, nor any prerequisites such as needing a valid scheme_code.

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