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

The annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: the default row omits wallet address and USD book, while include_diagnostics pulls in wallet address and position values and costs several kB per row of context. It also discloses the api:read requirement and the non-obvious id edge cases (a watch mints no id; a recorded ledger.status has a respondable id absent from the pending list, with the real pending id at ledger.existing_pending_recommendation_id).

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?

Purpose and the pending/history split are front-loaded, and nearly every sentence carries non-redundant information (id edge cases, book omission, diagnostics cost). It is a single very dense block, though, and the id/ledger caveat at the end could be separated for scanability rather than run on in the same paragraph.

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?

There is no output schema, and the description shoulders that burden fully by enumerating the lean row fields, the user_facing_recommendation slice, and what the diagnostics mode adds instead. Combined with the id semantics and auth requirement, an agent has everything needed to call it correctly and interpret the result.

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 only 33%, but the description compensates well for the two semantically loaded parameters: it defines the status enum values and spells out exactly what include_diagnostics returns and its privacy/context cost. The gap is limit: neither the schema nor the description explains what it bounds (pending rows vs history rows, ordering, default), so pagination behavior stays opaque.

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+resource (trade recommendations for the API key's user) and immediately splits it into the two modes status=pending and status=history. It also scopes itself against siblings by naming generate_recommendation as the source of the same row slice and respond_to_recommendation as the consumer of the ids, so an agent can place it without opening another schema.

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?

Explicitly says status=pending is for recommendations awaiting a response and status=history is the past ledger, and routes the agent away from this tool when it needs the book: 'use get_account_balances / get_positions when you need the book.' include_diagnostics has an explicit when-to-set-it condition ('set it only when you actually need the internals'), which is exactly the discrimination an agent needs.

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