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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds real operational context: newest-first ordering, a 100-entry page cap with next_cursor passed back as cursor, and the requirement for a Cotlet API key with app access. It does not cover failure behavior, but this is well above what the annotations alone convey.

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 purpose and sort order, then semantics, then pagination, then auth — a sensible information hierarchy with no filler. Slight density and the standalone 'customer payment has payment type Receive' sentence are minor overhead, but every sentence carries information.

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?

With no output schema, the description carries the full return-value burden and does so: it enumerates the fields each entry exposes and notes that each entry lists its allocated invoices, plus pagination mechanics and auth needs. Nothing essential for correct invocation is missing.

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%, so baseline is 3, and the description adds genuine meaning beyond the schema's bare enumerations: it explains what 'Receive' means (customer payment) and what each state implies for the General Ledger, and it clarifies the cursor round-trip. It adds meaning but does not touch every filter parameter (e.g., date-range intent).

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 and resource ('Lists Payment Entry records'), names the fields surfaced (party, amount, date, reference, state), and gives the sort order (newest posting date first). An agent can distinguish this from erpnext_list_sales_invoices and erpnext_list_overdue_invoices without reading 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?

The description explains domain semantics that help filtering (payment_type Receive = customer payment; state draft/submitted/cancelled with only submitted posted to the GL), which implies legitimate usage. However, it never states when to choose this tool over a sibling list tool, nor any exclusions or prerequisites beyond the auth note. Usage is implied rather than specified.

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