get_activity

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

With no annotations, the description must carry the behavioral burden. It discloses an auth/environment detail (POLYMARKET_WALLET_ADDRESS) and that it's a detailed audit trail, which is useful. But it doesn't say whether it requires specific permissions, how pagination interacts with the account-wide scope, or rate limits.

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 first two sentences are front-loaded and efficient, then it transitions to a standard Args block that is appropriate for the 0% schema coverage. There is minor repetition between the first and second paragraphs.

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 that an output schema exists, the description needn't explain return values. It covers the scope, the auth dependency, and all parameters, so it is sufficient for an agent to call it correctly, though it could be clearer on filtering precedence.

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 document the parameters. It does so for all four, including the activity_type enum values, which compensates for the schema gaps. It could add more on limit/offset defaults or constraints, but it meaningfully covers the parameters.

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 a clear verb+resource (retrieve an activity log) and enumerates the activity categories it covers (trades, splits, merges, rewards). It distinguishes itself from siblings like get_trade_history and get_positions by covering all account actions, though it doesn't explicitly name the alternative tools.

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?

It gives the context that this is an audit trail for the authenticated user and that it uses a configured wallet address, which implies when to use it. However, it doesn't explicitly say when to prefer this over get_trade_history or what conditions select it.

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