Output schemas not documented. Tools return data but LLMs have no specification of response structure, fields, types, or pagination. For example, get_portfolio and get_positions lack documented return types, forcing LLMs to guess what fields are available and how to chain results to downstream tools.
Parameter descriptions are minimal or absent. Most parameter descriptions consist of single short phrases (e.g., 'The broker to get portfolio from'). They do not explain valid formats, ranges, dependencies, or constraints. For example, 'trading_symbol' in create_order lacks guidance on format or accepted values; 'quantity' lacks min/max bounds; 'price' and 'trigger_price' lack rules for when they apply.
Document output schemas for all tools. Specify return type (object/array), field names, types, and nested structure. For example, get_portfolio should return an array of holding objects with fields: symbol (string), quantity (number), average_price (number), current_price (number), pnl (number). Include example output.
Expand parameter descriptions to specify format, constraints, and valid values. For 'trading_symbol', add: 'NSE trading symbol in uppercase (e.g., RELIANCE, INFY, WIPRO). Must be a valid instrument on the selected exchange.' For 'quantity', add: 'Positive integer representing shares or contracts. Minimum 1, maximum depends on broker limits.'
Restructure authenticate_broker to inject credentials server-side. Replace the 'credentials' parameter object with OAuth flow or a reference token. Never expose api_key, api_secret, access_token, or request_token in the tool interface.
Add recovery guidance to tool descriptions. For create_order: 'If order placement fails with insufficient margin, call get_margins() to check available funds. If symbol is invalid, call get_quote() with a partial symbol to discover valid instruments.' Similar patterns for other tools.
Document conditional parameter requirements. For create_order, add to the description: 'Note: price is required only when order_type=LIMIT; trigger_price is required only for order_type=SL or SL-M. For MARKET orders, omit both price fields.'
Add idempotency and confirmation hints. For create_order: 'This operation is IRREVERSIBLE. Consider calling get_quote() and get_margins() first to validate the order. No dry-run or confirmation mechanism exists, ensure parameters are correct before calling.' Similar warnings for modify_order and cancel_order.
Score history
Overall score trend
↓ 31 points across a rubric change (v1 → v2)
17/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-21
F
17
2026-07-28+
v2
2026-03-09
F
48
2024-11-05+
v1
Tool descriptions lack actionable guidance. Most descriptions (e.g., 'Get portfolio holdings for the authenticated broker') state WHAT the tool does but not WHEN to use it, what preconditions apply, or what the agent should do with results. LLMs cannot infer context from one-line summaries.
No error handling guidance. No tool description or parameter hints explain what to do if authentication fails, if an order is rejected, if a symbol is invalid, or how to recover. Agents will not know whether errors are retryable, user-fixable, or fatal.
No idempotency or confirmation for irreversible operations. create_order, modify_order, and cancel_order have high financial impact but lack dry-run, confirmation, or idempotency guidance. An agent error could execute unintended trades.
Credentials passed as parameters in authenticate_broker. The schema includes 'credentials' object with api_key, access_token, request_token, api_secret as explicit parameters. These secrets should never appear in tool signatures, they should be injected server-side via environment or vault. Credentials in parameters leak into logs and traces.
Parameter dependencies undocumented. In create_order, 'price' is required only for LIMIT orders; 'trigger_price' only for SL orders. These conditional requirements are not stated in parameter descriptions, forcing LLMs to guess or experiment.
get_session_info has empty input schema and vague description. The tool description is a bare function name with no explanation of what session info is returned, why an agent should call it, or when it is necessary.
get_session_info
Expand get_session_info description. Clarify: 'Returns current session metadata including authenticated user, active broker, session expiry, available balance, and margin utilization. Call this at the start of a trading session to confirm authentication and account status.'
Add permission scope declarations to tool descriptions. For example: 'Requires broker authentication and read access to portfolio data. Scope: read:portfolio.' Similar annotations for write/delete tools will guide least-privilege agent configuration.
Provide examples of valid enum values in parameter descriptions. For 'exchange', add: 'NSE (equity), BSE (equity), NFO (derivatives), MCX (commodities), CDS (currency). Most equity trades use NSE.' For 'product', add: 'CNC (long-term), MIS (intraday), NRML (normal for derivatives), CO (cover order), BO (bracket order).'
Introduce batch variants for frequently-called tools. Add create_orders (plural) accepting an array of order objects, and cancel_orders accepting an array of order IDs. This reduces token waste and latency for multi-leg trades.