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

La description ajoute des comportements non couverts par les annotations : 'Le premier passage sur un SIREN établit une référence silencieuse ; les changements suivants deviennent des alertes', ce qui est crucial pour comprendre l'effet de l'action. Elle précise aussi que la limite est la taille du portefeuille et non un compteur d'appels, apportant une transparence utile.

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?

La description est concise, bien structurée et va à l'essentiel : d'abord l'objet, puis les actions, puis les détails comportementaux. Chaque phrase apporte une information utile sans redondance.

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?

Pour un outil de gestion de portefeuille à trois actions et trois paramètres, la description est complète. Elle couvre les actions, les conditions d'utilisation, les limites, et les nuances de comportement. L'absence de schéma de sortie n'est pas un manque, car elle n'est pas indiquée comme nécessaire.

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?

La description explique le rôle du paramètre 'action' avec les valeurs possibles et la condition sur 'sirens' (requis sauf pour lister). Elle confirme l'importance de l'api_key. Cela compense le fait que le schéma ne fournit pas de description pour ces paramètres, et ajoute une sémantique claire.

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 clairement que l'outil gère le portefeuille de SIREN surveillés par Dataroia, avec une liste explicite des actions ('lister', 'ajouter', 'retirer'). Le verbe 'gère' est spécifique et le contexte (cessations, procédures collectives, etc.) distingue l'outil des frères comme surveillance_alertes.

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 précise les conditions d'usage : 'sirens requis sauf lister', la nécessité de la clé API, et les limites par plan. Elle oriente vers l'outil frère surveillance_alertes pour les alertes, ce qui aide à choisir entre les outils. C'est un exemple clair de contexte d'utilisation.

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