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

Annotations establish this is a non-read-only, open-world, non-idempotent write, but the description adds substantial context beyond them: keeper-executed persistence with the chat closed, the two possible outcomes (queued with stable requestId under status reserved/submitted, or needs_approval with an approval link signed in the Epsilon app), and the grant/cap condition determining which. This is exactly the behavioral detail annotations cannot carry.

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?

Dense but front-loaded: the core action and price semantics come first, then execution paths and status values, then sibling routing. Nearly every clause carries actionable information (keeper execution, requestId stability, HUMAN units) with no filler.

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?

For an 8-parameter mutation tool with no output schema, the description covers the outcomes an agent needs to interpret (status reserved/submitted vs needs_approval), the prerequisite check_order call, and the routing alternatives. Nothing essential for correct invocation is left implicit.

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 coverage is 100%, so the baseline is 3. The description nonetheless reinforces two semantics that matter for correctness: amounts are in HUMAN units and limitPrice is expressed as tokenOut per tokenIn with an 'or better' fill direction, plus the stable requestId retry behavior. It adds value on top of the schema without fully restating it.

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?

States a specific verb and resource ('place a resting limit order') and defines the trigger condition precisely (sell tokenIn for tokenOut once market reaches limitPrice or better). It explicitly distinguishes itself from the sibling order types place_stop_order and place_market_order, so an agent can route without opening schemas.

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?

Gives explicit routing rules: use place_stop_order for a protective sell below market, place_market_order for an immediate swap. It also states the prerequisite 'Run check_order first' and explains the two execution paths (agent grant within caps vs approval link), covering when the tool succeeds autonomously and when it will not.

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