Droits de l'utilisateur sur un enregistrement

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable context: the payload is returned as-is, keys vary by entity and are not normalized, and the RAML doesn't document them. This goes beyond annotations by setting expectations about output variability.

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 (Quand, Plutôt que, bullets, Returns), front-loads the core purpose, and uses no redundant words. Every sentence contributes to understanding when and how to use the tool.

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 simple 2-parameter read-only tool with no output schema, the description covers the purpose, usage context, alternative, behavioral caveats, and return format. It even addresses potential variability in the response, making it fully complete for an agent to call it 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% for both parameters, so the baseline is 3. The description adds a useful note that the available entities follow the server's access policy, which gives extra meaning about the entity parameter beyond its enum listing. This small addition justifies a 4.

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 clearly states the tool returns the authenticated user's rights on a specific record, listing example rights (read, write, delete, workflow actions) and the exact endpoint. It explicitly distinguishes itself from the global-rights tool, making its purpose unambiguous and differentiating it from siblings.

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 provides explicit when-to-use guidance (before uncertain *_update or *_delete calls) and when-not-to-use (instead of global rights via boond://application/current-user/rights), naming the alternative tool. This is exactly the kind of routing guidance that helps an agent select the correct tool.

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