Log a trade by hand

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

Annotations cover safety/idempotency, but the description adds real context beyond them: the OAuth LuxAlgo sign-in requirement, the duplicate-skip rule, the fill-to-trade derivation model (long = buy then sell, lone fill opens a position), and the return shape. That is substantive behavioral disclosure the annotations do not 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?

The core action and account constraint are front-loaded in the first clause, and each following sentence contributes distinct value (derivation rules, duplication behavior, return shape, exclusions, auth). Dense but free of 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 a nested-fills write tool with no output schema, the description supplies everything an agent needs: account eligibility, fill ordering/derivation semantics, duplicate handling, auth prerequisite, and a summary of what is returned.

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, but the description adds domain semantics the schema does not: ISO 8601 instants with offset, fees being per fill, and how side/sequence map onto trade direction. It goes past restating field descriptions without documenting every individual field.

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?

Specific verb (log/add) plus resource (fills into a journal account) with an explicit scope constraint: only `manual` or `import` accounts, never broker-synced ones. It also names journal_update_trade as the follow-up consumer of returned keys, so an agent can separate it from siblings 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?

States when to use it (hand-logging fills to manual/import journals) and when not to (broker-synced accounts, correcting or removing existing fills — done in the app). It routes the agent to journal_update_trade for subsequent edits, leaving little to inference.

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