Rechercher des paiements

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it explains that the 'fields' parameter is a client-side projection never sent to the API, that it replaces the summary with only the listed attributes, and that unknown names are ignored. It also notes the tool returns a list of matching payments. This is useful behavioral disclosure that goes beyond the structured annotations.

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?

The description is well-structured with clear sections: purpose, when to use, alternatives, args, and returns. It is slightly verbose with the French accents and some redundancy (e.g., 'Conserves pour compatibilite' is a bit terse but informative). Overall, every sentence earns its place and the most important scoping information is front-loaded.

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 search tool with 11 optional parameters, no required parameters, and no output schema, the description covers the key usage aspects: what it returns, how to filter, pagination, and the special 'fields' projection behavior. It does not explain every parameter (e.g., resourceId, purchaseId, projectId are only in the schema), but the schema already covers those with 100% description coverage. The description is complete enough for an agent to select and invoke the tool correctly.

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 the baseline is 3. The description adds value beyond the schema by explaining the special keyword syntax (ACH<id>, CSOC<id>, PRJ<id>) and by clarifying that invoiceId and companyId are kept for compatibility and passed as query params if provided. It also explains the 'fields' projection behavior, which is not fully captured by the schema's short description. This exceeds the baseline.

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 states a specific verb and resource ('Recherche des paiements / reglements dans BoondManager') and clearly distinguishes it from sibling tools by naming boond_provider_invoices_search and boond_purchases_search as alternatives for different resources. It also explains that a payment is attached to a purchase and does not replace it, which removes ambiguity.

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 explicitly says when to use this tool ('pour suivre les règlements enregistrés') and names the alternatives to use instead for provider invoices and purchases. It also provides concrete guidance on keyword formats (ACH<id>, CSOC<id>, PRJ<id>) for filtering by purchase, company, or project, which is actionable usage guidance.

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