Modifier une prestation/livraison

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

Beyond the annotations, the description reveals that updates are partial (only supplied fields are written), that array-typed fields are replaced rather than merged, and that rights should be verified beforehand via `boond_rights_get`. It also discloses the return value, a confirmation and the updated record. These details significantly extend what the idempotentHint and readOnlyHint annotations 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?

The description is front-loaded with the core action, then organized into Quand, Plutôt que, bullet points for key behaviors, and a Returns line. Each statement earns its place, there is minimal redundancy, and the structure makes it easy to parse quickly.

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?

Given the 10-parameter schema and output schema, the description covers all essential decision points: purpose, when to use, alternative tool, partial-update semantics, array replacement risk, and the recommended rights pre-check. No critical usage detail is missing for an agent to 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?

All 10 parameters have full descriptions in the schema, so the baseline of 3 applies. The description's partial-update statement clarifies how parameters behave in aggregate, but it adds no per-parameter meaning beyond the detailed schema definitions. The schema already documents mappings, formats, and dictionary references for each field.

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 first sentence states a precise action, 'Met à jour un(e) livraison (CRA) existant(e), identifié(e) par son ID', which clearly identifies the verb, resource, and scope. It explicitly contrasts with `boond_deliveries_create`, so an agent can distinguish it from the most similar sibling. The title and description are fully aligned.

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 gives an explicit 'Quand' condition ('modifier quelques champs d'un enregistrement déjà en base') and an explicit alternative with condition ('Plutôt que boond_deliveries_create si l'enregistrement n'existe pas encore'). It also advises checking `boond_rights_get` before attempting to avoid a 403, which is concrete operational guidance.

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