prepare_deposit

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

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses that the tool creates a local immutable draft, makes no network calls, does not invent licenses, and that metadata_update is a full replacement rather than a patch. These are meaningful behavioral traits beyond what the schema could express.

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 dense but efficient: it front-loads the core purpose, then adds workflow preconditions, operation semantics, and a key behavioral constraint ('Aucun appel réseau') without filler. Every sentence contributes information needed to invoke the tool correctly.

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 complex tool with nested publication metadata and no output schema, the description is unusually complete: it states preconditions, operation-specific behavior, no-network behavior, and the required user-facing step before submission. It does not explicitly mention validate_deposit in the workflow or describe the returned draft structure, but the absence is minor given how clearly the tool's role is scoped.

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 0%, so the description must compensate. It adds real meaning to operation, pdf_path, target, license_url, and structure_ids. Portal and environment are not explained, but their enum values and defaults make them largely self-explanatory, so the description covers the parameters that genuinely need semantic clarification.

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 and resource: 'Créer un brouillon local immuable ART/COMM' (create an immutable local ART/COMM draft). It clearly differentiates this from siblings by framing it as the local preparation step before submit_deposit, and it explicitly defines the three operation modes. An agent can tell what this tool does and how it relates to the deposit workflow.

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 gives actionable workflow guidance: resolve structure_ids in AuréHAL before preparing, verify check_duplicates, and present the full result to the user before submit_deposit. It also explains when each operation variant applies. It does not explicitly mention validate_deposit as an alternative or state when not to use this tool, so it falls just short of full routing guidance.

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