get_hedge_recommendations

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: it computes net portfolio delta, suggests both stock and option hedges, and clarifies that recommendations are share-equivalent not beta-weighted. It also notes a prerequisite (fetch Greeks via get_options_chain). It does not mention any side effects (e.g., no data persistence) but for a read/computation tool this is adequate.

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 an intro, usage bullets, Args, and Returns sections. It is a bit long due to the JSON example, but every section earns its place. The bullet list makes usage conditions easy to scan. Slightly verbose but not wasteful.

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 tool is moderately complex with 3 parameters and no output schema. The description explains inputs thoroughly, describes the output ('Current vs target delta and concrete hedge suggestions'), and even mentions a dependency (get_options_chain). This is enough for an agent to select and invoke correctly, though it does not detail the exact hedge calculation or edge cases.

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?

Despite the input schema having no property descriptions, the description provides rich parameter semantics: a full JSON example for 'positions', a note that plain text works for stock-only portfolios, and explicit default values for 'hedge_ticker' and 'target_delta'. This fully compensates for the 0% schema coverage.

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 a clear, specific verb: 'Get delta-hedge recommendations for a portfolio.' It then details what the tool computes (net delta vs target, stock and option hedge alternatives) which fully distinguishes it from sibling tools like get_portfolio_greeks (which only computes greeks) or build_strategy (which constructs strategies).

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 explicit 'Use this tool when...' bullets covering hedging, delta-neutral, and protective puts. It does not explicitly state when not to use it or name alternatives, but the listed use cases are clear and actionable. The guidance is solid, though not fully exhaustive with exclusions.

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