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

Goes well beyond the readOnlyHint annotation: it warns that extraction comes from a language model and may be wrong, requires user validation before any downstream write, and discloses that each call consumes the account's monthly analysis quota — a cost/rate-limit fact an agent must know. It also states the accepted formats, the 10 MB ceiling, the MCP_FILE_PATH_PREFIX prerequisite for file_path, and that all amounts are in euros.

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?

Front-loaded with purpose and the 'no creation' guarantee, then the input modes, limits, and next steps in a logical order. It is dense but every sentence carries operational weight; the only mild redundancy is restating mode exclusivity that the schema already declares.

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 extraction tool with no output schema, the definition covers everything an agent needs: what it returns (a structured draft entry, not a persisted record), the confidence caveat and required human validation, the mandatory downstream chaining, cost implications, and input constraints. Nothing material is left for the agent to infer.

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 100%, so the schema already documents the three mutually exclusive file inputs, filename inference, property_id, and the document_type value list. The description reinforces the mode exclusivity and adds the env-var prerequisite, but adds no new semantics for individual parameters beyond what the schema states; baseline 3 applies.

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?

States a specific verb and resource ('Analyse un justificatif … et retourne une proposition de saisie structurée'), enumerates the concrete document types handled (facture, avis de taxe foncière, attestation d'assurance, tableau d'amortissement, relevé bancaire), and explicitly negates creation ('SANS RIEN CRÉER'), which separates it from the create_* siblings in the same family.

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?

Gives clear workflow guidance: it names the four follow-up tools (create_expense / create_furniture / create_property_work / attach_document) and the condition for proceeding, namely that the user has validated the values. It also declares the three input modes mutually exclusive. It stops short of stating any exclusion case (e.g., what to do if the document is already structured, or when not to analyze), so it is strong context rather than a full when/when-not rule set.

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