Créer une action

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

Le description comporte des informations comportementales au-delà des annotations : « Returns: L'action créée avec son ID» expose le retour ; la contrainte « positioningId requis par l'API pour les types d'action liés aux positionnements (ex. RQ)» et l'erreur associée apportent un contexte de négociation. Les annotations indiquent déjà readOnlyHint=false, idempotentHint=false et destructiveHint=false, ce qui est cohérent avec une opération de création. La description n'ajoute toutefois pas plus de détails sur les effets (par exemple, elle n'insiste pas sur le fait que l'opération n'est pas idempotente, la création de doublon possible, mais cela est déjà suggérée par la comparaison à update).

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?

Description assez longue mais bien structurée : une première phrase qui énonce l'objectif, puis une phrase de guidance (« Plutôt que... »), puis une liste `Args:` en bullets. Chaque ligne apporte une information (format de date, contrainte relationnelle, compléments commerciaux). Il y a une certaine redondance avec le schéma (chaque paramètre y est listé), mais la description est utilisable seule et front-load les informations clés. Un cran de plus serait possible si elle omises les list d'Args pour pointer vers le schéma, mais la taille reste raisonnable pour un outil avec 12 paramètres.

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?

Avec 12 paramètres, un output en sortie non spécifié et une opération de création, la description fournit presque tout ce qu'un agent seek : les types d'actions, la nécessité d'une entité de rattachement, le format dates, l'exigence de `typeOf` via la dictionnELIN, la contrainte de `companyId`, et le retour avec id. Manque peut être un exemple d'appel complet, mais ce n'est pas indispensable puisque le schéma a déjà une couverture à 100%. Il serait possible d'ajouter les prérequis d'authentification ou de politique, mais ces informations ne sont pas plus attendues pour un tool d'API.

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?

Le schéma de l'objet couvre 100% des paramètres avec des descriptions, donc la baseline est à 3. La description dépasse ce baseline en ajoutant des sémantiques transversales : elle regroupe les cinq identifiants de messagerie potentiels et précise « un requis » (contrainte qui the net est pas exprimée dans le schéma formulé, car seule `typeOf` est requise). Elle explique aussi la relation `dependsOn` obligatoire et l'incompatibilité de `companyId` sauf en complément d'un `contactId`. Ce sont des informations nécessaires pour appeler l'outil correctement, non visibles dans le schéma seul.

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?

La description indique un verbe d'action précis (« Crée une nouvelle action »), précise les types d'actions (appel, email, RDV, note), l'univers BoondManager et les entités de rattachement (contact, candidat, ressource, opportunité, projet). Elle différencie explicitement de sa sœur boond_actions_update (« Plutôt que : `boond_actions_update` »), ce qui permet à un agent de sélectionner correctement l'outil dès la lecture.

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?

La description indique explicitement dans quels cas ne pas utiliser : « Plutôt que : `boond_actions_update` pour compléter une action déjà enregistrée plutôt que d'en créer un doublon ». Elle précise aussi une condition d'usage importante : une entité de rattachement doit être fournie (« relation dependsOn, obligatoire », « contactId | candidateId | ... (string, requis) »). Ceci guide l'agent vers le bon choix entre création et modification, et impose une contrainte critique pour réussir l'appel.

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