calculate_trade

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a pure computation via the verb 'Calculate' and the phrase 'before logging a trade' hints that it does not itself log, but it never explicitly states read-only behavior, whether it makes network calls (e.g., fetching prices), requires special permissions, or has any side effects. For a tool in a trading context, where an agent might confuse calculation with execution or recording, this ambiguity is a real gap.

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?

Two sentences with no fluff: the first front-loads the tool's outputs, the second gives timing. Every word earns its place. It loses a point only because the brevity also skims past behavioral information that, with no annotations on the tool, an agent would benefit from.

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?

With neither annotations nor an output schema, the description itself must communicate what the agent gets back; the four named outputs partially cover this. However, it does not clarify whether the computation requires prior price fetch for market_id, how fair_value affects the results, or whether the tool is safe to call at any point. For a six-parameter calculation helper this is adequate but incomplete — an agent could call it correctly yet be surprised by missing prerequisites or ambiguous return shape.

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 100%%, so every parameter already has meaning in the input schema, meriting the baseline 3. The description names output metrics (risk/reward ratio, max gain/loss) but does not explain how they relate to inputs like fair_value, stop_loss, or size_usd; the optional fair_value parameter's role in the calculation is left untouched. No value beyond the schema is added, but none needed for a 3.

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 uses a specific verb and resource ('Calculate trade parameters') and enumerates concrete outputs (position sizing, risk/reward ratio, max gain, max loss), so an agent knows roughly what this tool produces. It does not explicitly differentiate itself from siblings like generate_execution_plan or compare_markets, but the 'calculate' framing and output list make the purpose clear enough.

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?

'Use before logging a trade' gives clear temporal context and tells the agent where this tool fits in the trading workflow. It does not, however, name alternatives or exclusions — e.g., there is no guidance on when to prefer generate_execution_plan or when this tool is unnecessary — so it stops short of a 5.

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