Supporter transaction history

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

With readOnlyHint and openWorldHint already covering the safety profile, the description still adds meaningful behavior: the history list carries no amounts while recurring schedules do, max_results caps each list separately, and card details and payment-gateway references are never returned. That privacy/field-omission disclosure is real value beyond the annotations, though it omits anything about rate limits, pagination beyond the cap, or permissions.

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 dense sentences, front-loaded with what the tool returns, then two short sentences on the most surprising semantics (where amounts live, what is never returned). Every clause carries information; nothing restates the title or name.

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, so the description must describe the return payload, and it does: both lists, their contents, the presence/absence of amounts, and the redaction guarantee. Combined with a fully documented 4-parameter schema, an agent has everything needed to call this correctly.

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 goes further by spelling out the shape of recurring schedule data (amount, currency, frequency, status, next payment date) and by clarifying that max_results applies to each of the two lists independently. It does not explain include_contact_details' redaction behavior, which the schema already handles.

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 names the resource precisely (a supporter's transaction history) and enumerates exactly which activity types are included: donations, event tickets, petition signatures, emails to targets, data captures, peer-to-peer activity, plus recurring donation schedules. That level of enumerative specificity clearly separates it from siblings like find_supporter and query_supporters, which locate supporters rather than return their history.

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?

Usage is implied by the resource description — an agent can infer this is the tool to call once a supporter_id is known — but there is no explicit when-to-use, when-not-to-use, or named alternative. The schema hints supporter_id comes from find_supporter or query_supporters, which supplies some routing context, but the description itself offers no selection guidance.

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