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

Annotations already declare the safe read-only, idempotent, non-destructive profile, and the description adds real context beyond that: what the widget displays, that it carries Préparer une relance / Changer d'étape / Voir dans Ficiel buttons, and how it resolves ambiguous person matches. It stops short of noting any auth or visibility constraints, but for a read-only view this is solid added value.

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 core action is front-loaded ("AFFICHE UN WIDGET") before the parenthetical field list, so an agent can stop reading early and still know the tool's purpose. The long enumeration of widget contents is dense but earns its place by telling the agent what to expect on screen; nothing is redundant.

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 read-only widget tool with no output schema and only 3 parameters, the description covers what the agent needs: what is shown, the action buttons available, and how to supply the identifier plus the ambiguity fallback. The main missing piece is explicit routing against lookalike siblings such as ficiel_get_lead.

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 coverage is only 33% (only contact is documented, as pseudo/nom/numéro). The description compensates partially by restating the three identification keys and clarifying that any one of them identifies the person and that contact accepts pseudo, name, or number. It does not state precedence when several are supplied, nor that all three parameters are optional despite 0 being required.

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 opens with a specific verb+resource ("AFFICHE UN WIDGET : la fiche d'une personne") and enumerates exactly what the widget contains, so the agent knows precisely what it produces. It implicitly distinguishes itself from data-returning siblings like ficiel_get_lead by being a widget view with action buttons, but never names those siblings or contrasts against them explicitly.

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 gives useful operational guidance on identifying the person (conversation_id, lead_id, or contact) and what happens on ambiguous matches (a list of lead_id to choose from). However it never states when to reach for this tool instead of ficiel_get_lead, ficiel_get_lead_context, or ficiel_get_conversation, leaving the choice to inference.

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