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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds the crucial nuance that archiving preserves the file and its usages, which materially tempers how an agent should interpret the destructive hint. 'Version obligatoire' also signals an optimistic-concurrency precondition not visible in the annotations, though restore behavior for archived assets remains unstated.

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?

Four short sentences, front-loaded with the operation list before the sibling cross-references, with no filler. The clipped fragment 'Version obligatoire' is efficient but telegraphic, and the French prose against English tool names adds slight parsing cost.

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 6-parameter mutation with safety annotations already present and no output schema, the description covers purpose, alternatives, archival semantics, and the required version. It stops short of stating what the call returns or whether an archived asset can be reactivated.

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?

With 0% schema description coverage, the description carries the burden and largely meets it: rename→name, folder→folder, describe→description, archive→status, and version is called out as mandatory. Only `id` is left unexplained — the description never says which asset identifier must be supplied — so one of six parameters lacks semantic grounding.

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 uses concrete verbs tied to the resource ('Renommer, classer dans un dossier, décrire ou archiver un média du projet courant'), and each verb maps to a distinct metadata field. It also explicitly separates itself from two siblings by naming upload_asset for import and create_record (type posters) for poster creation.

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 clear routing guidance: use upload_asset to import, create_record for posters, this tool for renaming/foldering/describing/archiving. The gap is the reverse routing — an agent is not told when this tool is the wrong choice, e.g. whether posters or other record types should be updated via update_record instead.

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