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

Annotations already declare readOnly=true and destructive=false, but the description adds real behavioral context: offline payments already deduct from the total due on the proposal, online payments are refundable while offline are not, and each row carries online/offline origin and status. It also states the auth requirement (Cotlet API key with app access). Only return-format/pagination detail is missing.

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?

Front-loaded with the payment types and scope, and most sentences carry distinct information (refundability, deduction semantics, auth). The opening 'Perfect Venue: Payments of one event' is slightly redundant with the title, but the rest is efficient.

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 single-parameter read-only tool with no output schema, the description covers what the rows contain, their online/offline nature, status, refundability, and the auth requirement. An agent has enough to call it correctly; only return-shape details are omitted, which is minor for a read listing.

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 100% and the single parameter (event_id) is already documented as 'Event ID from list_events.' The description adds no format or source detail beyond the schema, so baseline 3 is appropriate.

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 (list) and resource (payments) scoped to one event, and enumerates what the rows contain: deposits, scheduled payments, offline payments with amount, method and date. It also distinguishes itself from sibling refund_payment and log_offline_payment by explaining the online/offline distinction. An agent can identify the tool without opening the schema.

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?

Gives clear context (retrieve the Payments tab rows for a single event) and names the alternative for the follow-up action: online payments can be refunded with refund_payment, offline cannot. It stops short of explicitly stating when to choose this over siblings like get_event or list_events, so it lacks full when/when-not routing.

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