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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds real value by disclosing that 'The checkout token is never returned' (a data-omission guarantee an agent cannot derive from annotations) and by specifying that amounts are in cents. It stops short of covering auth needs or error behavior for unknown ids.

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?

Two compact sentences plus the endpoint, all front-loaded: identity and scope first, then field inventory, then the negative guarantee. The field list is long but earns its place because there is no output schema.

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 correctly compensates by enumerating the returned fields and noting the excluded checkout token, so an agent can plan on the response shape. It does not describe behavior for a nonexistent or invalid payment_id or any pagination/expansion options, which is the remaining gap.

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?

Only one parameter and schema description coverage is 100%, with the schema itself noting the id comes from moonclerk_list_payments. The description adds nothing beyond 'by id', so the baseline 3 is appropriate — the schema does all the semantic work.

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 specific resource and scope ('One MoonClerk payment by id') and makes the retrieval verb explicit with 'GET /payments/{id}', which clearly separates it from the sibling list_payments. It also enumerates the payload fields, so an agent knows exactly what it gets back.

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 only implied: the singular 'by id' scope signals this is the single-record fetch versus moonclerk_list_payments, but the description never states when to choose it or when not to. There are no explicit alternatives or prerequisites in the description text itself (the sibling pointer lives only in the schema's parameter description).

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