Get holdings

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

With no annotations, the description carries the full burden of behavioral disclosure and does so well: it states 'Read-only', explains the limitation of no current price/market value/P&L, and documents the transformation of API fields into quantity/averagePrice and NSE scrip code. This is meaningful behavioral context beyond a simple action verb.

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 two dense sentences with the key scope and limitation front-loaded. Every phrase adds information: read-only, return fields, exclusions, downstream routing, and normalisation behavior, with no filler.

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 no-input read-only endpoint without an output schema, this is nearly complete: it defines return semantics, the critical omission (no market value), and how results should be consumed downstream via get_quotes and analyze_allocation. The only minor ambiguity is the mechanics of 'normalised', but an agent still has enough to invoke the tool and interpret its output.

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?

There are zero parameters and the schema is empty, so the baseline is 4 and there is no parameter detail for the description to add. The mention of 'normalised' adds useful output/behavior context but does not fully resolve how that representation is requested, which keeps it from a 5.

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 first sentence names a specific resource ('long-term delivery holdings') and a read-only retrieval action. The second sentence sharpens scope by enumerating what is returned (quantity, average price per scrip) and explicitly excluding current price, market value, and P&L, which clearly separates it from valuation tools like get_quotes.

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 strong workflow context: pass security_ids to get_quotes to value the book, and use the normalised vocabulary for analyze_allocation. It does not explicitly state when to prefer get_positions or other holdings-related siblings, so the guidance is clear but not exhaustive.

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