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

No annotations exist, so the description carries the full behavioral burden. 'Fixed JSON GET' implies a read, and 'Explicit company required' discloses a scoping requirement, but there is no mention of pagination, permissions, or result behavior; an output schema covers return values but not the calling behavior.

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 short sentences, front-loaded with the endpoint and the company requirement. Little waste, though the raw path notation is terse to the point of opacity.

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?

An output schema helps, but for a 3-param tool with 0% schema coverage and no annotations, the description leaves filters, pagination, and sibling differentiation largely unspecified. It is too thin for the tool's complexity.

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 0%, so the description must compensate. It does add meaning—'Flat query fields' characterizes the query object and points to describe_nextesy_operation for filter details—and the endpoint path implies purchaseId. But purchaseId and company_name semantics remain only lightly covered by 'Explicit company required'.

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 exposes the raw endpoint 'GET /api/v1/sales/purchases/{purchaseId}/payments', which conveys that it retrieves payments for a given purchase. However, it never states the purpose in plain language and does not distinguish it from nearby siblings like get_purchase or get_purchase_settlements.

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?

'Explicit company required' states a prerequisite, and the pointer to describe_nextesy_operation hints at filter discovery, but there is no when-to-use guidance and no contrast with alternatives such as get_purchase_settlements.

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