calculate_portfolio_greeks

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It clearly explains the input format (JSON array with detailed fields), notes that option Greeks should be sourced from get_options_chain, and mentions the return value ('Aggregated portfolio Greeks with risk assessment'). It does not disclose edge-case behavior (e.g., invalid input, missing Greeks) or explicitly state that it is read-only, but the compute-only nature is obvious. This is adequate but not exhaustive, hence a 4.

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 clear sections: purpose, usage cases, arguments with an example, and return value. The example is lengthy but necessary to document a complex JSON input format. Every sentence serves a purpose—no filler. It is front-loaded with the main verb and resource, making it easy to scan.

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 complexity of the tool (one string parameter with a JSON structure), the description is thorough: it covers input format, prerequisites, and the nature of the output. However, it omits edge cases (e.g., empty portfolios, invalid position types, required fields per position type) and does not detail the risk-level assessment criteria. With no output schema, a bit more on the return structure would make it fully complete, but it is strong for the given context.

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 schema only declares 'positions' as a string, but the description provides a complete, annotated JSON example with all required fields (ticker, position_type, quantity, current_price, strike, expiration, delta, theta, vega). It also clarifies that plain text works for stock-only portfolios, adding semantics far beyond the schema. This is a textbook case of description-driven parameter documentation.

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 opens with 'Calculate aggregate Greeks for a portfolio of positions' — a specific verb ('calculate') and resource ('portfolio') with a clear scope ('aggregate'). It explicitly lists the key outputs (net delta, theta, vega, risk-level assessment) and differentiates from sibling tools like get_greeks_heatmap, which focus on individual symbols. The intent is unmistakable and distinct.

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 explicitly states when to use the tool: 'Use this tool when the user asks about: Portfolio Greeks, Net delta/theta/vega, Position exposure.' It also provides a prerequisite ('Get option Greeks from get_options_chain first'), guiding the user through the correct workflow and implying that this tool is not for fetching raw Greeks (which get_options_chain handles). This is clear usage guidance with direct alternatives implied.

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