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

Goes well beyond the lone destructiveHint annotation by disclosing the deferred, two-phase lifecycle: the gift is matched to a contact/recurring gift/pledge, held until the nightly import, and only created after a human reviews and clicks Run. That is exactly the kind of non-obvious side-effect timing an agent needs before calling a write tool.

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?

Four dense sentences, front-loaded with purpose, then behavior, then donor identification, then the upstream endpoint. No filler; the endpoint reference at the end is terse and contextual rather than padding.

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 17-parameter, nested-object tool with no output schema, it covers the essentials: what gets created, when, what does not happen (no charge), and how the donor is identified. It doesn't touch the deferred-import failure/preview mechanics or how designations and recurring frequency interact with contact matching, but the safety and lifecycle essentials are present.

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 71%, so the schema already carries much of the load, but the description adds real value by explaining the three donor-identification strategies (contact.id, contact.referenceId, or name/email details) and the contact-matching behavior, which is not stated in the schema. It doesn't clarify attribution/designation or dedup semantics beyond what the schema provides.

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 ("Record a gift... through Virtuous's gift import pipeline") and scopes it precisely enough to distinguish it from sibling read tools like virtuous_get_gift and from the separate virtuous_create_contact_transaction path. The parenthetical "donation already received" removes ambiguity about whether money is being moved.

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 clear context ("the method Virtuous recommends") and an important negative exclusion ("it does NOT charge anyone"), which steers the agent correctly. It stops short of explicitly naming the alternative path — e.g. when to prefer virtual_create_contact_transaction over this import pipeline — so the routing is implied rather than stated.

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