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

Annotations already cover the read-only, non-destructive, closed-world profile, so the bar is lower. The description still adds real value by disclosing the authentication prerequisite ('connexion demandée la première fois') and by enumerating the returned fields in the absence of an output schema.

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 sentences with no filler; the field enumeration is dense but purposeful. The caller/authentication context leads, which is slightly less important than the resource identity but not wasteful.

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 one-parameter read tool with annotations and a field list, most of what an agent needs is present. The remaining gaps are the lack of any cue on behavior when the reference is unknown, and no signal on how this differs from the many sibling payment/transaction lookups.

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?

The single parameter is fully documented in the schema (100% coverage), including its dual nature as a payment reference (token) or a link code, and the description restates that same fact. Baseline 3 applies since the schema already carries the parameter semantics and the description adds no new constraints.

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 resource (a payment) and enumerates exactly what is returned — montant, frais, net, moyen, pays, statut, dates, lien concerné — which gives an agent a concrete picture of the tool's output. It never explicitly contrasts itself with close siblings such as etat_paiement or detail_transaction, so the differentiation is left implicit.

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 states the caller context ('pour l'utilisateur connecté à son compte Tchin, marchand ou particulier') and the lookup key ('avec la référence du paiement ou le code du lien'), which is useful usage framing. However, there is no explicit when-to-use versus when-not, and no mention of when an agent should prefer etat_paiement or detail_transaction instead.

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