detect_order_blocks

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

No annotations are provided, so the description carries the full burden. It describes the computed heuristic and that results may vary from other definitions, which is useful. However, it doesn't disclose the return format beyond 'Estado: fresh/mitigated/broken', doesn't mention data requirements (how many candles needed), or performance considerations. For a compute-heavy analysis tool, this feels thin.

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 compact and front-loads the key heuristic. The Spanish is technical and precise. It wastes little, though it could have front-loaded the purpose statement more clearly before diving into the heuristic formula.

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 (algorithmic indicator, 5 params, output state machine), the description covers the algorithm but leaves out operational context: what data is needed, what error conditions exist, what the output structure is (though output schema exists). The heuristic explanation is solid, but for an indicator tool with no annotations, the lack of when-to-use guidance is a notable gap.

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 for 5 parameters. It explains displacement_factor (in the heuristic), lookback implicitly via '200 default', only_unmitigated not mentioned, symbol/interval obvious. The description explains the core heuristic so the displacement_factor and lookback semantics are derivable, but only_unmitigated's behavior is completely undocumented.

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 detects order blocks using a specific displacement heuristic with concrete details (displacement_factor × ATR(14), last opposite candle in prior 3). It has a clear verb+resource and matches its name. It doesn't explicitly distinguish from detect_fvg, but the heuristic detail is strong enough to stand alone.

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 explains the heuristic definition and notes it's computational, but gives no guidance on when to use this vs detect_fvg or get_market_structure, and no context on typical trading scenarios or data requirements. The note "HEURÍSTICA computada" warns about differences from other OB definitions, but doesn't route the agent to an alternative.

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