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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, lowering the burden. The description adds valuable behavioral context: 'paper-trading decisions only — no real-money order routing', the log nature, and that outcomes are included. It also notes prerequisites and caveats, going beyond the structured safety profile without contradicting it.

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 compactly structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, Args, Disclaimer). Every section adds distinct value, though the trigger examples are somewhat repetitive. Overall, it is well-organized and front-loaded with the core purpose.

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 4 parameters, output schema presence, and rich annotations, the description covers all necessary aspects: purpose, usage context, prerequisites, next steps, caveats, and parameter semantics. It does not need to describe return values because an output schema exists. Minor gaps are acceptable (e.g., exact outcome format), so it is complete for practical invocation.

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 0%, so the description must compensate. The Args section gives meaningful semantics: market_id with accepted values and aliases, limit with default, decision_filter enumerates choices (buy, sell, hold), hours_back explains 'only decisions within last N hours'. This adds purpose to each parameter beyond the bare schema.

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 clearly states the tool's purpose: 'Track-B (signal-driven) paper-trading decision log', with an explicit contrast to Track A (LLM judgement path) via 'see get_llm_trading_decisions'. It names specific verbs like 'review recent automated decisions and their outcomes', which distinguishes it from siblings and explains its scope.

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 provides explicit usage guidance: 'When to call', example triggers, prerequisites ('market://{market_id}/status recommended'), and next steps ('get_trade_history, get_signals'). It also differentiates from alternative Track B vs Track A, directing to get_llm_trading_decisions for the other path, which fulfills the when/when-not requirement.

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