Wallet activity & behaviour

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses conditional key-dependent behavior (OpenSea only 'with a key', transfers only with OPENSEA_API_KEY set), states computed outputs (P&L before fees, behavior label with reason), and explicitly acknowledges data blind spots: 'Every figure says which feed it came from and what that feed cannot see.' This openly discloses limitations rather than hiding them, going well beyond what annotations already provide. No contradiction with annotations.

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?

Three sentences with the core scope front-loaded before the detail enumeration. The first sentence is a long run-on listing eight output categories, which is dense but each item earns its place for a tool this complex. Sentences two and three are tight single-purpose statements covering the key condition and provenance/auth. Slightly heavy, but appropriately sized for the breadth of what the tool returns.

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?

With no output schema, the description's enumeration carries the return-value spec, and it is impressively detailed: totals, flows, marketplace identification, flips with hold time and P&L, behavior labels with reasons, and per-figure feed provenance. The main gaps are the absence of edge-case behavior (empty wallet, no trades in window) and no sibling-routing guidance, but for a tool this broad the description is nearly self-sufficient.

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 adds behavioral meaning beyond the schema: it explains includeOpenSea's purpose (answering 'was this airdropped, gifted or bought?' via plain transfers), ties it to the OPENSEA_API_KEY requirement, and connects the pages parameter to the 'window' containing the first purchase. These enrich the cold schema descriptions with rationale and dependencies.

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 opens with 'How a wallet trades' and enumerates the tool's specific outputs: SOL totals, net flow, listings and bids, marketplace identification (Magic Eden order book vs AMM pools), most-traded collections, flips with hold time and P&L, and a behavior label with reason. This unmistakably differentiates it from siblings like get_wallet_holdings (what a wallet owns) and get_wallet_profile (static profile), so an agent can separate it without opening the schema. The noun-phrase opening is the only minor weakness, but the scope is precise and comprehensive.

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 invocation context: 'Read-only; needs no key' and a conditional behavior when OPENSEA_API_KEY is set (transfers included so airdrop/gift/purchase questions get evidence-based answers). However, it never names an alternative tool or states when NOT to use this one, leaving the agent to infer that get_wallet_holdings or get_wallet_profile cover adjacent questions. Guidance is implied but never explicit.

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