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

The annotations already declare readOnlyHint=true and destructiveHint=false, signaling a safe read operation. The description adds valuable behavioral context beyond that: data provenance ('decoded from the Wanchain governor's own events'), inclusion criteria ('every successful transaction... and every governor transaction that paid it'), and the format trait that amounts are base-unit integer strings. No contradiction with annotations exists; the read-only claim aligns with the decode/list framing.

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 phrase 'Governance activity for a Wanchain address' is front-loaded, immediately establishing the tool's core purpose. Every clause in the single sentence adds meaningful specification (source, inclusion criteria, content fields, asset types, and amount format), so nothing is wasted. The sentence is somewhat long and run-on, with a trailing enumeration that could be broken up, which prevents a 5.

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 one-parameter, read-only tool with no output schema, the description carries the return-value burden and does so well: it enumerates what is returned (proposal, vote, pledge mechanism, voting power, assets WAN and XP in/out, base-unit strings). Missing details are minor — the overall response structure (array vs object) and address format are not specified. Given the tool's low complexity, the description is nearly complete.

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 carries the burden of explaining the 'address' parameter. It does add meaning by clarifying the address is a Wanchain address in a governance context, which goes beyond the bare schema string type. However, it omits practical detail such as the expected address format (e.g., hex prefix or checksum), so compensation for the coverage gap is only partial.

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 states a specific resource (a Wanchain address) and a specific scope of activity (governance activity decoded from the governor's own events, including proposal, vote, pledge mechanism, voting power, and asset flows). This sharply distinguishes it from the sibling tools like get_address_activity and get_address_flows, which cover general activity and flow data, and get_address_positions, which covers holdings. The detail about 'every successful transaction it sent to the governor' makes the exact semantics unmistakable.

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 usage context is implied through the description's specificity: an agent seeking governance-related activity (votes, pledges, proposals) for a Wanchain address would infer this is the right tool. However, the description never explicitly names alternatives or states when not to use it, such as pointing to get_address_activity for non-governance activity. No exclusion or routing guidance is provided.

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