immobilier

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, and the description adds genuinely non-derivable behavior: the output is a draft only, no listing is ever published through MCP, publication is reserved for the Synergieloc operator via manual validation, and publier=true is rejected. It also cites the backing REST route, which helps the agent understand the call's scope.

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 the trigger condition, then the action, then the critical constraint. Slight redundancy between 'aucune publication sur synergieloc.fr via MCP' and 'publier=true est refusé', though the emphasis is defensible for a constraint that must not be missed. Four sentences, no filler.

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?

With 14 optional parameters and no output schema, the description compensates by naming the return shape (texte_brut + html) and by explaining the statut='brouillon' constraint that governs the whole call. Nothing needed to invoke it correctly is missing.

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% across all 14 parameters, and those descriptions already carry the substantive semantics (DPE classes A-G with F/G restrictions, loyer hors charges with rent-control caveat, statut fixed to 'brouillon'). The description adds no per-parameter meaning beyond what the schema provides, so the 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 ('Rédige un BROUILLON d'annonce de location') plus the exact output form (texte_brut + html). It also draws a sharp line between drafting and publishing, so an agent can tell it apart from any diffusion/publishing path in the sibling set (mandat_gerance, candidature_locataire).

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?

Opens with an explicit trigger condition ('QUAND un bien vacant doit être mis en location et qu'il faut rédiger l'annonce') and an explicit exclusion (no publication via MCP, publier=true refused). It does not name a sibling alternative, but the when-to-use and when-not-to-use conditions are both stated directly.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds substantial extra context: the return artifact is printable HTML with a PDF endpoint, the layout is always formatted for a window envelope (recipient on the right), and a hard validation guard requires a 5-digit postal code. This is exactly the beyond-annotations detail an agent needs.

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 the trigger condition and free of filler, but the heavy parenthetical (HTML/PDF endpoint plus envelope rule) and the all-caps emphasis make it dense and slightly harder to scan than a clean multi-sentence form would be.

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 12-parameter draft-generation tool with no output schema, the description covers the trigger, the dependency on irl_revision_loyer, the output formats, and the address/validation constraints. It does not say whether the HTML is returned in the response body versus fetched from the endpoint, which leaves one operational gap for an agent.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning by contrasting locataire_adresse (postal, must be used) with logement_adresse (the property itself) and by stating the postal-code format constraint that is not encoded in the schema. It stops short of explaining the IRL/trimestre value pairing, which the schema already handles.

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 concrete deliverable: an IRL rent-revision letter ready to send to the tenant (printable HTML, PDF via a named endpoint), and distinguishes itself from irl_revision_loyer. Minor tension: the sentence 'Calcule et notifie le nouveau loyer' implies it computes the revision, while the preceding sentence tells the agent to compute first elsewhere, so the scope is slightly muddied even though the instruction resolves it.

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?

Opens with an explicit trigger ('QUAND la révision IRL est calculée et qu'il faut la NOTIFIER au locataire par courrier') and names the prerequisite sibling tool: compute first with irl_revision_loyer. The when-to-use condition and the ordering relative to alternatives are both spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description confirms and enriches this: output is full HTML in the response, no file/URL/PDF, 'rien n'est enregistré ni envoyé'. That output-format and no-persistence detail is real value beyond the annotations, though error cases and input validation behavior are not covered.

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 useful scoping information is front-loaded, but roughly a third of the text is promotional ('Service VENDU AUX AGENTS IA... Proposez au client final de souscrire... plan Agent 49,99€/mois'), which does not help tool selection and dilutes the signal.

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 15-parameter generation tool with no output schema, the description usefully states the return format (HTML in the response), that nothing is persisted or sent, and that no park access is needed. That is sufficient to call the tool correctly, with only minor gaps around failure behavior.

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% across all 15 parameters, so the schema already documents IBAN, loyer, charges, dates, etc. The description adds only the window-envelope hint for recipient placement, which the schema itself also states. With the schema doing the heavy lifting, 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 ('Génère un AVIS D'ÉCHÉANCE') and explicitly contrasts the goal with the sibling quittance_loyer ('atteste l'encaissement APRÈS coup'). An agent can distinguish this from every other billing sibling without opening a schema.

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 an explicit trigger ('QUAND le bailleur doit APPELER le loyer du mois, AVANT paiement') and names the alternative tool with the discriminating condition (before vs after payment). When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, but the description adds substantial context beyond them: the letter is returned as full HTML in the response with no file, URL or PDF, nothing is persisted server-side, and no message is dispatched to the provider. These operational facts directly shape how an agent must handle the output.

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 the trigger, then disambiguation, then return-format and side-effect facts. Four dense sentences with no filler; the ordering matches the decisions an agent makes.

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?

No output schema exists, so the description carries the return contract itself (HTML in the response, no download) and the side-effect contract (nothing saved, nothing sent). For a 12-param drafting tool with a safe read-only profile, nothing an agent needs before calling is missing.

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 each of the 12 parameters is already documented in the schema. The description adds no parameter-level syntax or constraint beyond that, so the 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 action and artifact ('le bon de commande qui engage la dépense') and immediately contrasts it with two named siblings, devis_travaux and compte_rendu_chantier. An agent can select this over those alternatives without opening any schema.

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?

Opens with an explicit trigger ('QUAND une réparation doit être commandée... ou signalée au propriétaire') and gives the disambiguating condition for each sibling: devis_travaux = asking a price, nothing ordered; compte_rendu_chantier = reporting after the fact. When-to-use and when-not are both covered.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description still adds valuable context: free, no API key, 0 units, public rules only, server-side guardrails remain authoritative, and the exact return shape. It stops short of describing versioning semantics or refresh behavior, so not a 5.

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 the WHEN directive and information-dense throughout; every clause carries content. It is a packed run-on spanning several ideas, which slightly hurts scanability but wastes no words.

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?

No output schema exists, and the description compensates by outlining the returned object structure and the domains covered. For a single-optional-parameter read tool with full annotations, nothing an agent needs to invoke it correctly is missing.

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 coverage is 100% and the enum already enumerates all domains, including the 'omit to receive all domains' behavior that the description repeats. The description adds no filter syntax or semantics beyond what the schema documents, so the 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 action (read a versioned playbook of best practices) and the exact resource, plus what it contains (public MCP/API rules, no tenant data). It is immediately distinguishable from every sibling, which are all task-specific domain tools rather than meta-guidance.

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 explicit invocation timing: call it FIRST on server discovery, and again if cached instructions may be stale. That is a clear when-to-use trigger that no other sibling provides, and it implicitly excludes routine data operations.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavior beyond that: the PDF retrieval route and the instruction to file the result locally ("À classer dans le dossier local après réception"). It does not mention auth, quotas, or error behavior, so it stays at a solid 3.

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 telegraphic fragments with the usage trigger front-loaded and no filler. It is appropriately sized, though the fragmentary, clipped style slightly reduces readability and structure compared to full sentences.

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 17-parameter tool with no output schema, the description does give the output format and destination, which is the main missing piece. It still omits what the caller receives concretely, where the HTML is written, and any permission or prerequisite context for generating the dossier.

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% across all 17 parameters, including the notable caveat that pieces_jointes carries labels only, not documents. The description adds nothing about parameters, so the baseline 3 applies — the schema does all the explanatory work.

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 identifies the artifact produced ("Dossier de CANDIDATURE locataire") and its formats (HTML, PDF via /api/v1/documents/candidature), but never states the action verb — it is left implicit that the tool generates the dossier. A reader must infer the operation from the artifact name rather than from an explicit verb+resource pairing.

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 front-loaded "QUAND un candidat constitue son dossier pour un logement" gives a clear situational trigger for invocation. However, it names no alternative tool and states no when-not conditions, so routing among the many sibling document tools is still left to inference.

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

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

Annotations already cover read-only, non-destructive, closed-world, so the safety profile is settled. The description adds real output behavior: one step per trade with dates, SVG axonometric and ground-floor plan per step, and the optional single-date state — valuable since there is no output schema.

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?

A single dense paragraph, front-loaded with the WHEN trigger and the 4D framing before the trade vocabulary and return description. Slightly run-on but every clause carries information about output structure or classification.

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 15-parameter, all-optional, no-output-schema tool, the description supplies the missing return-value picture (per-trade steps, dates, two SVG views, single-date state). The input scene schema is inherited and well documented elsewhere, so little is left unexplained.

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 15 scene parameters are already fully documented in the schema, which sets the baseline at 3. The description adds domain framing (trade classification, schedule derived from model quantities) but no parameter-level detail beyond the schema.

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 ('show the model as built at a date') and pins the semantics precisely with '4D, as Navisworks links a model to a schedule'. It is clearly the only scheduling/sequencing sibling among the cao_* export tools, though it never names an alternative explicitly.

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?

Opens with an explicit trigger ('WHEN the building must be shown AS IT WILL BE BUILT over time'), which is a clear usage context an agent can match. It offers no when-not guidance or named alternatives (e.g. cao_permis, cao_pdf) for overlapping use cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes further, disclosing selection semantics (IFC GlobalId, camera in front) and the return payload {topics, conflits, alertes, bcf_base64} with the instruction to write bcf_base64 to a .bcfzip file — useful context beyond the annotations.

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-loads the trigger condition and packs topic granularity plus return shape into a few dense sentences with no filler. Slightly long, but every clause (readers, topic type, GlobalId, camera, return keys) earns its place for a format-critical export.

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?

No output schema exists, but the description compensates by naming the returned keys and telling the agent how to persist bcf_base64. Combined with 100% schema coverage and clear read-only annotations, an agent has enough to invoke it correctly.

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 13 parameters at 100% schema description coverage, the schema already carries the detail. The description adds only the high-level 'pass a scene or ifc' branch, which is largely already stated in the ifc parameter description ('When given, scene fields are ignored'). 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 (export) plus resource (clashes and issues) and output format (BCF 2.1 zip), and explains the granularity (one Clash topic per clash, one Issue topic per alert). This clearly separates it from siblings like cao_conflits_ifc or cao_generer_ifc.

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 leading 'WHEN clashes and control alerts must leave as a BCF 2.1 zip readable in Solibri/BIMcollab/Navisworks/Revit/Archicad' gives a concrete trigger condition. It lacks an explicit 'instead use X' routing to siblings such as cao_conflits_ifc, so it stops short of 5.

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

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

With readOnlyHint=false already flagged, the description adds real behavioral context: enregistrer creates a new version only when the definition changed ('unchanged definition: no new version'), which explains the idempotentHint, and lister anonymizes other users' families behind an 'anonymous author code', a privacy behavior not visible in annotations. It still says nothing about permissions, quotas, or failure modes.

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 trigger condition is front-loaded and every clause carries information (per-action behavior, the prerequisite tool), with no filler. It is dense and slightly crammed into two long sentences, which costs a point against a tighter, better-segmented layout.

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, multi-action tool with one nested object and no output schema, the description covers all three actions, the nested `famille` payload's purpose, and the required prerequisite step. It does not describe what lister or lire actually return beyond the families themselves, leaving some return-shape ambiguity.

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 coverage is 100% and each parameter already documents the action it applies to (lire, enregistrer), so the schema carries the load. The description mostly restates those action-to-parameter mappings ('publique' to share, 'version' default latest) rather than adding syntax or format detail, so the baseline of 3 is appropriate.

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 names the specific resource (the account's persistent family library) and enumerates its three modes (lister/lire/enregistrer) with a helpful Revit-family-library analogy. It clearly differentiates itself from cao_famille_essayer, but it does not distinguish itself from the closely named siblings cao_familles and cao_familles_recharger, which an agent would need to tell apart.

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 opens with an explicit trigger ('WHEN a parametric family ... must be reused across projects or shared') and states the prerequisite workflow ('Build and test the family first with cao_famille_essayer'). There is no guidance on when NOT to use it versus the sibling library tools, so it falls short of a 5.

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

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

Annotations already declare this a safe, non-destructive, non-open-world read, so the bar is lower. The description nevertheless adds genuine behavioral commitments beyond them: views are printed at TRUE SCALE ('never a false one'), every sheet carries a title block with revision table and an 8-character model fingerprint, and the exact return shape is described.

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 the WHEN trigger, then the sheet composition, then the scale policy, then the return shape. Dense but every sentence carries information an agent needs. The single long paragraph hurts scannability slightly, blocking a 5.

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 13-parameter, nested-object tool with no output schema, the description closes the important gaps: it explains what is produced, the scale guarantee, the contents of the title block, and the exact JSON return ({feuilles, empreinte, html}). Nothing an agent needs to invoke it correctly is missing.

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% across 13 parameters, and each field is documented in the schema itself (units, defaults, frame conventions). The description adds no parameter-level guidance of its own, so the baseline of 3 is appropriate.

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 states a concrete verb and resource: it 'builds numbered A3 or A1 sheets' with an enumerated sheet set (cover, site plan, plans per storey, elevations, section, MEP plans, schedules). That is far more specific than the title alone. It does not, however, name any sibling (e.g. cao_pdf or cao_generer_dxf) to sharply delimit its scope, so it falls short of a 5.

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?

A clear WHEN clause ties the tool to a real decision point: issuing a design as a drawing set for a client, a planning application, or a contractor. It gives context but no exclusions and no named alternative (e.g. when to reach for cao_pdf instead), which is the remaining gap.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: geometric matching by wall endpoints, openings, and object type/position rather than index, so deletion does not cascade into false modifications. It also discloses the return structure field by field and item by item.

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 front-loaded with the WHEN condition and remains focused on the comparison logic and outputs. It is somewhat dense and could be split for readability, but every sentence contributes useful selection or behavioral context.

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?

Despite having no output schema and nested object inputs, the description explains the comparison method and the returned categories (added, removed, modified, quantity differences) sufficiently for an agent to understand what it gets back. Annotations cover the safety profile, and the schema covers input shapes.

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 avant, apres, and quantites. The description reinforces that quantites drives an item-by-item quantity take-off comparison, but adds little syntax or format meaning beyond what the schema provides.

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 states a specific verb and resource: comparing two versions of a building model. It also specifies the exact outputs (added, removed, modified elements plus quantity take-off differences) and explains the geometry-based matching, which distinguishes it from a naive index-based diff and from the sibling merge tool.

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 clearly says WHEN to use it: to see what a client, architect, or another agent changed and to derive the basis of a change order. It does not explicitly name alternatives or state when not to use it, but the usage context is clear and actionable.

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

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

Annotations already declare a safe read-only operation, but the description adds substantial behavior beyond them: the clash threshold, the volume/slice computation method, which interpenetrations are deliberately excluded as intended geometry (bearings, corner/T joints, rug/deck objects, doors in walls), and the exact return keys. This is well past the lower bar set by the annotations.

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 the WHEN clause and the core detection rule, followed by input modes and exclusions. Dense and occasionally long-winded, but nearly every clause carries technical payload rather than restating structured fields.

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?

Although there is no output schema, the description supplies the return shape ({conflits, ignores, elements, boite_modele}), the input alternatives, and the false-positive policy. For a clash-detection tool with 13 documented scene parameters, nothing an agent needs to call it correctly is missing.

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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics: the scene-vs-`ifc` choice, that scene fields are effectively superseded by `ifc`, and that GlobalIds are preserved from the IFC. It thereby disambiguates the primary input decision the schema alone leaves open.

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+resource (detect clashes / real interpenetrating solids) and pins the operational definition (>10 mm and 0.1 L on volumes), so it is unmistakable against siblings like cao_verifier or cao_valider_ifc. The concrete examples (nested tables caught, bed against a wall not) make the intent self-evident.

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?

"WHEN coordinating a BIM model" gives a clear triggering context, and it authorizes two input modes (a scene same as cao_generer_ifc, or raw `ifc` text). It does not name an alternative tool or state when not to use this one, so the routing is implied rather than explicit.

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

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

Annotations already cover safety posture (readOnlyHint true, destructiveHint false, openWorldHint false), and the description adds substantial behavior beyond them: deterministic rules vs. language model, millimetre precision, cascading edits (attached walls extended, furniture followed, obstacles pushed, switches relocated), and a validation gate that rejects defective walls and forbids moving a load-bearing wall alone.

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 the WHEN trigger and written as a dense but well-ordered chain (trigger → transformation → safeguards → return shape → downstream). It is long and semicolon-heavy without bullet structure, but nearly every clause carries information an agent needs.

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?

With no output schema, the description compensates by enumerating the full return object ({compris, source, operations, journal, erreurs, nouvelles_alertes, valide, scene, difference}) and by explaining validation, deterministic fallback, and downstream routing. Nothing required to invoke or interpret the tool is missing.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it points to the operation catalogue endpoint (GET /api/v1/cao/copilote) and specifies that supplied operations are 'applied without the language model', clarifying the relationship between the `operations`, `instruction` and `modele` parameters.

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 ('change an existing building scene') and enumerates concrete instruction types (move a wall, widen a door, rotate furniture) that map to the typed operations the tool produces. It also positions itself against siblings by noting the resulting `scene` is forwarded to cao_generer_ifc or cao_pdf, so an agent can distinguish editing from generation.

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 'WHEN a user asks to change an existing building scene in plain words' clause gives an explicit trigger with representative French utterances. It implies generation is a separate sibling but never states when NOT to use it, nor names an alternative editing/validation tool such as cao_verifier.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered; the description goes further by disclosing that it is FREE with no API key and 0 units, that it returns JSON rather than a drawing, and that dimensions are in millimetres. It also explains the failure mode it prevents (openings.z misuse, storeys without windows), which is genuinely useful context beyond the annotations.

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 the WHEN directive and organized under clear headers (WHY IT MATTERS, GOOD CALL, DO NOT), so an agent can skim it. It is somewhat long and repetitive between the schema enum text and the GOOD CALL examples, which keeps it just under the top mark.

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?

There is no output schema, but the description compensates by explaining that the return is JSON containing the scene plus the ordered next calls, and it names the downstream tools (cao_verifier, cao_pdf, cao_generer_dxf, cao_generer_ifc). Nothing needed to invoke and chain the call is missing.

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% and the enum already documents all three values, so the schema carries the parameter burden. The description largely restates the enum meanings (house / flat / veranda) rather than adding syntax or constraints, so the baseline 3 is appropriate.

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 action (return a complete, pre-verified example building scene as JSON) and explicitly contrasts it with the sibling cao_verifier. The described output ('hands back a COMPLETE, ALREADY-VERIFIED scene plus the exact next calls in order') is concrete enough for an agent to know exactly what it gets.

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?

Explicit WHEN clause ('about to draw ANY French building for the first time...'), a GOOD CALL section naming three concrete invocations, and a DO NOT section that names the alternative (cao_verifier) for the check case. Nothing about routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds genuinely useful behavioral context beyond them: it auto-completes from the CAO scene "completed by the rules if needed" and never invents prices, surfacing unpriced items in sans_prix. What happens to input geometry is not fully described, but the pricing contract is explicit.

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 the WHEN clause, then a single long trade enumeration that is dense but earns its place by scoping the tool's coverage. The final sentence carries the pricing contract compactly; nothing is obviously redundant.

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 14-param, nested-schema, no-output-schema tool the description covers the essential purpose, price-input contract and the sans_prix output hint. It does not explain how scene inputs map to returned item codes or the overall result structure, which would help given the absent output schema.

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 coverage is 100%, so the schema already documents all 14 params. The description nonetheless adds value by foregrounding the two params that drive output totals (`prix`, `tva_pct`) and naming the returned sans_prix convention, which the schema alone does not connect.

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 states a specific verb+resource: it computes trade-by-trade QUANTITIES to price a house (the skeleton of a French DPGF), enumerating the covered trades. However it does not distinguish itself from close siblings like cao_metres, cao_nomenclatures or devis_travaux, leaving the agent to infer the boundary.

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?

"WHEN a client or a contractor needs the QUANTITIES to price a house" gives a clear use context, and the price-handling rule (pass your own prices, unpriced items go to sans_prix) is stated. There is no explicit when-not or a named alternative to route to, so it stops short of full guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value beyond them by disclosing the return content ('alerts, applicable correctifs and the coverage per level') and cost/auth context ('Free, no key'). It does not explain the appliquer/revalider behaviour visible in the schema.

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?

Three dense sentences, front-loaded with the WHEN trigger, then the rules, then the return and cost. Nothing is redundant, though the rule enumeration is packed tightly into a single sentence.

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?

With annotations present, no output schema, and a fully documented (if shared and oversized) input schema, the description covers purpose, trigger, return shape and cost adequately. It could note which scene fields are relevant to the check, but overall an agent has enough to call it correctly.

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% across all 14 scene parameters, so the schema already carries parameter meaning and the baseline is 3. The description adds no parameter-level guidance (e.g. which fields the completeness check actually consumes), leaving the schema to do all the work.

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 states a specific check (drawing-set completeness) and enumerates exactly what it verifies: one plan per level, stair access to each upper floor, guardrails per NF P01-012. It explicitly distinguishes itself from the sibling cao_verifier, which 'already includes it', so an agent can tell the two apart without opening a schema.

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?

'WHEN you need the drawing-set completeness check alone' gives the selecting condition, and naming cao_verifier as the tool that already bundles this check effectively points to the alternative. It stops short of an explicit when-not (e.g. 'do not use if you also need electrical/structure checks'), but the routing signal is clear.

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

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

Annotations already declare read-only, non-destructive, non-open-world behavior, and the description adds real context: climate data and carbon factors come from the caller and 'nothing is guessed,' plus that shading factors are measured on the scene's own sun paths. It does not address failure modes or validation limits, so it falls short of a 5, but it adds meaningful behavioral context beyond the annotations.

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 a WHEN clause and organized into method → inputs → exclusions, so the key routing signal arrives first. It is dense and heavy with parentheticals, making it a wall of text, but for a 16-parameter tool with no output schema nearly every clause carries information.

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?

There is no output schema, so the description must convey return content — and it does, listing the computed outputs (heating need, DHW, final/primary consumption, embodied carbon, summer check). Combined with its statement of external data dependencies, an agent has enough to call and interpret the tool correctly.

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 coverage is 100%, so the baseline is 3. The description goes further by clarifying the role of caller-supplied inputs — climat (degree-days, irradiation), facteurs_carbone (emission factors), and systeme (generator) — and explains that quantities are derived from the bill of quantities, linking semantics to specific parameter groups. This is useful context beyond the schema text.

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 names a specific verb+resource (estimating energy performance) and enumerates exactly what is computed: heating need via degree-day method, DHW, final/primary energy, embodied carbon, and a summer overheating check. It explicitly differentiates from the sibling cao_re2020 by stating it is 'NOT a French DPE nor the regulatory RE 2020 calculation,' so an agent can route correctly.

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 WHEN clause specifies the triggering user intents (cost to run, climate cost, summer overheating) and the closing sentence gives an explicit exclusion and implicit alternative (cao_re2020). Both when-to-use and when-not-to-use are stated, which is the top of the scale.

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

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

Adds real behaviour beyond the readOnly/destructive/openWorld annotations: it enumerates the exact expression grammar evaluated ('arithmetic, comparisons, min/max/round, a if c else b; nothing else is evaluated'), states the output is in mm, and explains that placement happens later via `familles`/`instances` in a CAO scene. Annotations confirm safety; the description supplies the evaluation semantics they cannot.

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-loads the WHEN condition and keeps every clause informative, but the run-on second sentence packs the expression grammar, return payload, and placement instructions together and could be broken up for scanability.

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?

With no output schema, the description correctly describes the return payload (computed values, constraint findings, solids in mm) and explains how the result reaches a scene as boxes/IFC objects. For a two-param, nested-object tool with annotations covering safety, little is missing beyond an explicit sibling reference.

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 coverage is 100% and both parameters are fully documented in the schema, so the baseline is 3. The description restates the family structure (parameters, formulas, constraints, solids) without adding syntax or format detail the schema lacks, so it neither helps nor hurts.

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: 'try a family DEFINED AS DATA, like a Revit family', with the scope (typed/bounded params, formulas, constraints, solids) made explicit. It implicitly carves itself out from catalogue-based siblings by saying 'no catalogue has', but never names cao_familles or cao_bibliotheque_familles, so an agent must infer the split.

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 'WHEN a custom parametric object is needed that no catalogue has' clause gives a clear triggering condition with concrete examples (shelf, counter, pergola, technical box). It does not name the catalogue sibling it is meant to be used instead of, nor state when NOT to use it, so routing is implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnlyHint, non-destructive, closed-world), so the description's added value is behavioral detail: `famille`+`parametres` entries are validated (out-of-series refused, French 24 Dec 2015 accessibility decree) and exported to IFC as a shared-geometry door/window type. It also notes the tool is free and needs no key, which is genuinely useful. The status of the enumerated joinery list versus the later validation/export flow is slightly blended, keeping it at 4.

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 trigger condition is front-loaded in the first clause and the sentences are dense but purposeful. The long parenthetical enumerations of family types are borderline but serve discoverability, since there is no schema or output schema to list them elsewhere.

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?

With no input parameters and no output schema, the description carries the burden of explaining what the call yields and it does so: the family catalog with bounded parameters and bay sizes, plus the validation and IFC export behavior. It is nearly complete, missing only how the list is delivered (grouping, paging, format).

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?

The tool takes zero input parameters, so per the rubric the baseline is 4. The description references the payload fields that matter downstream (`famille`, `parametres`, `ouvertures[]`), but since there is no input schema to disambiguate, it cannot exceed the baseline.

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 states a concrete verb and resource: it lists parametric joinery families (hinged/double/sliding/pocket/entrance doors, French windows, sliding patio doors, tilt-and-turn/fixed windows) with their bounded parameters and resulting bay sizes. That is far more specific than the title. It does not, however, explicitly distinguish itself from near-siblings such as cao_bibliotheque_familles or cao_famille_essayer, so it falls short of a 5.

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?

Usage is clearly framed: 'WHEN you place doors or windows in a scene and want real, orderable joinery instead of free-size holes.' This gives an unambiguous trigger context. It never names an alternative tool or states when NOT to use it, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds genuinely useful conditional behavior (a version that would reject already-placed instances is reported and the old version kept), but 'reload/update' sits in mild tension with a read-only hint and no persistence semantics are clarified.

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?

Three tight sentences with the trigger condition front-loaded ahead of the behavior and return value. Every clause carries information, with only minor redundancy between the title and the opening clause.

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 one-parameter tool with no output schema, the description usefully covers the return value ('the updated scene and what was reloaded') and the failure branch (old version kept), which compensates for the missing output schema. The nested 'scene' object's internal shape is left to the schema.

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% with a single required 'scene' parameter, so the schema already documents the only input. The description adds no syntax or format detail for 'scene' beyond what the schema states, so the 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: reload the families of a scene from the library, explicitly analogized to Revit's 'Reload Family'. It is easy to distinguish from siblings like cao_familles or cao_famille_essayer because it names the exact action (move to latest version).

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?

Opens with an explicit WHEN condition (scene uses library-placed families AND the library has newer versions), which is strong triggering guidance. It does not, however, name alternative tools (e.g. cao_famille_essayer or cao_bibliotheque_familles) or state when NOT to use it.

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

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

Annotations already declare readOnlyHint/destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that the description adds genuine domain behavior: the normative basis (Eurocode 2, C25/30, B500), the explicit edge-case rule (slabs too thin for their span are flagged rather than over-reinforced), and the liability boundary ('pre-design... to be validated by a structural engineer').

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?

One dense but front-loaded paragraph: the WHEN condition and scope come first, then the calculation content, then the caveat. Every clause carries information, though the length hurts scannability for an agent skimming candidates.

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 12-parameter composite scene tool with no output schema, the description explains what is computed but not what must be supplied: it never says that murs[] is the operative input or that most other fields (reseaux, toitures, plomberie, decoration, electricite) are irrelevant to this calculation and only feed cao_pdf. That omission leaves a real gap in knowing how to invoke the tool correctly.

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% and the schema documents every input in depth, so the structured data already carries the parameter burden. The description adds output vocabulary (bars, kilograms) but nothing about input parameters, so 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?

The description names a specific computation (load path per wall, SLS/ULS combinations, simplified EC2 reinforcement of footings, lintels and slabs) and its output form (bars such as '3 HA12', kilograms of steel). It is clearly a structural pre-design tool, but it never contrasts itself with the closest siblings (cao_regles_structure_reseaux, cao_metres), leaving that differentiation to inference.

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 leading WHEN clause gives an explicit triggering context: a house design that needs its structural pre-design for costing. It does not state when NOT to use it, nor name an alternative tool, so it stops short of a full 5.

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

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

Annotations only declare a safe read profile; the description adds substantial behavior: conflicts are returned, never silently overwritten; a delete-vs-modify on the same element is flagged; openings survive a wall deletion; elements keep persistent identity (ifc_guid / external_id); a base hash mismatch is refused with 409. This is far beyond what readOnlyHint/destructiveHint convey.

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 the WHEN condition and dense with useful detail; the wall/opening example earns its place by illustrating conflict behavior. It is long and occasionally packed with parenthetical asides, but no sentence is redundant.

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 three-way merge with no output schema, the description covers conflict handling, identity keys, the resolutions flow, and the integrity/error case, and notes that the answer carries SHA-256 hashes of all versions and the result. It stops short of describing the returned conflict/result structure in detail, but the essentials for a correct call are present.

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 coverage is 100% so the baseline is 3, but the description earns more: it explains the semantics of `resolutions` ({conflict id: central | local}) and of `empreinte_base` (SHA-256 of the loaded base, mismatched base refused with 409) and clarifies the identity model for elements. It adds real meaning over the schema's terse one-liners.

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 states a specific operation — a three-way, element-by-element and field-by-field merge of concurrent edits to the same house design — which clearly separates it from siblings like cao_comparer_versions (diff) and cao_conflits_ifc (conflict listing). The 'what' arrives after a long WHEN clause, and the sibling alternatives are implied rather than named, so it falls short of a 5.

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 opening WHEN clause gives concrete triggering conditions ('two people or agents changed the same house design in parallel, starting from the same version, and both changes must be kept') plus an analogy (Revit central model sync). It never states when NOT to use it or points to cao_comparer_versions/cao_conflits_ifc as the lighter-weight alternatives.

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

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

Goes well beyond the readOnly/openWorld annotation trio by disclosing delivery semantics: the DXF arrives INLINE as text, there is no download URL and no file on the server, so the caller must persist it. It also names the alertes[] channel for unresolved geometry issues — exactly the operational context an agent cannot infer.

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 the WHEN clause before any mechanics, and every sentence is load-bearing: condition, action, prerequisite, schema pointer, return shape, alternative. No restatement of the name or title.

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 12-parameter, deeply nested scene tool with no output schema, the description supplies the missing return contract (dxf/faces/entites_2d/unites/note/alertes), the inline-delivery caveat, a prerequisite, and an escape hatch to the sibling. Nothing an agent needs to invoke it correctly is absent.

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% and the nested murs/boites/plan/etc. properties are richly documented, so the schema carries parameter meaning. The description adds no parameter-level detail (units, frames, defaults), so the baseline 3 for high-coverage schemas is correct.

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+resource ('Draw a building scene and get an AutoCAD DXF') and explicitly distinguishes itself from the sibling cao_generer_ifc by output type (lines vs BIM objects). An agent can route between the two CAD generators without opening either schema.

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?

Opens with a clear WHEN condition ('the drawing must leave as a real CAD file'), gives a prerequisite ('Call cao_verifier first to catch geometry mistakes'), and names the alternative and its selecting condition ('Choose cao_generer_ifc instead when the recipient needs BIM objects'). When, prerequisite and alternative are all explicit.

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

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

Goes well beyond the readOnly/destructive annotations: it discloses that the IFC returns inline with no download URL and nothing stored server-side, that GlobalIds are stable across exports when projet_id is passed, that doors/windows really cut host walls, that output passes schema/EXPRESS validation, and that armatures adds Eurocode-2 reinforcement. This is exactly the behavioral context annotations cannot carry.

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 'WHEN…' clause is front-loaded and the content is dense but largely earns its place for a 13-parameter, nested, no-output-schema tool. However several ideas are crammed into single run-on sentences (the return-value and armatures points could be separated), which reduces scannability.

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?

Given no output schema and a complex nested input, the description compensates fully: it explains the returned object shape ({ifc, elements, unites, schema}), how the inline IFC must be written to disk, the units, georeferencing, and the validation guarantees. An agent has everything needed to invoke and consume the result.

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 coverage is 100%, so the baseline is 3; the description still adds meaning by naming parameters and their effect beyond the schema text (projet_id for GlobalId stability, compositions{} to replace type compositions, armatures:true for IfcReinforcingBar/IfcReinforcingMesh, poteaux[]/poutres[] becoming IfcColumn/IfcBeam). It also references parameters (poteaux, poutres, projet_id) not present in the shown schema, which is slightly confusing.

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?

Names a specific verb and resource ('Draw a building scene and get an IFC4 file in millimetres') and enumerates the concrete IFC output (spatial hierarchy, IfcColumn/IfcBeam, IfcSpace, IfcRoof, IfcStair, Pset/Qto). It also distinguishes itself from siblings, explicitly contrasting with cao_generer_dxf ('Same scene as cao_generer_dxf') and pointing to cao_valider_ifc/cao_verifier.

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?

States the triggering condition clearly ('WHEN the drawing must leave as a real BIM file, openable in Revit/ArchiCAD/Solibri — not just a drawing') and names the alternative path (cao_generer_dxf for the same scene, cao_valider_ifc to validate locally, cao_verifier to call first). When-to-use and sibling routing are both explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered; the description adds real behavior beyond that — per-specification output with failing elements and reasons, and that `bcf: true` produces BCF 2.1 topics. It could have clarified it never mutates the input and what the base64 payload entails, so 4 rather than 5.

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-loads the WHEN clause, which is good, but the body collapses specification scope, return shape and the default-IDS note into one dense, dash-heavy run-on sentence that is hard to parse. Nearly every clause carries content, but the packaging works against readability.

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?

No output schema exists, so the description must carry return semantics; it does describe per-specification results and BCF output. However, with 15 parameters dominated by scene-construction fields (murs, boites, toitures, ouvertures…), the description never explains how those inputs feed the check, leaving a substantial mismatch between the described tool and its actual schema unaddressed.

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 every parameter; baseline is 3. The description clarifies the semantics of `ids` (default French housing IDS) and `bcf` (adds failures as BCF topics), but does not touch the many scene-construction parameters (murs, boites, plan, etc.), which is the bulk of the schema.

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: check an IFC model against an IDS 1.0 requirements file, with a precise enumeration of what is checked (entity, attribute, property, classification, material, partOf). It differentiates itself from the many cao_* siblings by naming IDS conformance specifically. It does not explicitly contrast with the closest siblings (cao_valider_ifc, cao_verifier, cao_conflits_ifc), so a 4 rather than 5.

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 a clear triggering condition ('WHEN a BIM manager's information requirements must be checked on a model before delivery') and clarifies the fallback path (no `ids` = French housing IDS). It distinguishes the two input modes (scene-built model vs. architect's IFC). No explicit when-not or named alternatives, so 4.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond that: what the conversion preserves (GlobalId/ifc_guid per element), what each flag produces (conflits adds clashes, studio opens a 4K video studio and VR tour), and the return payload. One minor tension: 'studio:true opens the ... video studio' implies a side effect for a tool annotated read-only, though it is likely just URL generation.

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 WHEN-condition and the conversion outcome are front-loaded, and every clause carries information. It is dense — long em-dash chains mixing French domain terms (rapport, controles, metres) with the English framing — but no sentence is filler.

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?

There is no output schema, so the description takes on return-value disclosure and does it well: it names the four returned keys and explains two of them (controles = cao_verifier audit, metres = quantities). Combined with the element list, flag behavior, and the reuse instruction, an agent has everything needed to call and consume it.

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 baseline is 3. The description still adds meaning by tying the flags to concrete outputs (metres = quantities, conflits = clashes, studio = video studio + VR tour) and by specifying the accepted IFC dialects (IFC2X3 or IFC4). The `controler` flag is only indirectly implied by 'check it with our rules'.

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 ('converts the IFC text into a CAO scene') and enumerates the extracted element types (walls, doors/windows hosted on walls, stair flights, railings, named rooms, furniture, roof). An agent can separate it from siblings like cao_valider_ifc, cao_conflits_ifc or cao_generer_ifc, which imply validate/clash-check/generate rather than import-and-convert.

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?

Front-loads a clear trigger: 'WHEN an architect sends an IFC ... and you must check it with our rules'. It also routes onward usage ('Reuse `scene` with every other cao_* tool'), which is useful sequencing guidance. It stops short of naming which sibling to pick when the goal is pure validation or clash-only checking.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: it names the return payload (alerts plus applicable `correctifs` field→value), explains that appliquer:true yields the corrected scene, and states it is free with no key required (auth/cost info). It stops short of describing alert structure or severity levels.

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 selecting WHEN-clause is front-loaded and the return/behavior sentence follows, so the ordering is agent-friendly. The parenthetical defect list is long but each item is a concrete check, so it earns its space; the string is dense in one paragraph rather than wastefully padded.

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 14-parameter, nested-schema tool with no output schema, the description covers the essentials an agent needs: what it checks, what it returns, the appliquer/revalider behavior, and cost/auth. What it does not cover — alert shape, severity, or how correctifs map back to the scene — is a modest remaining gap rather than a blocker.

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 coverage is 100% across 14 parameters, so the schema carries the diagram-geometry burden and the baseline would be 3. The description adds meaning for `appliquer` beyond the schema's 'Apply the proposed fixes to a copy of the scene' by tying it to the returned corrected scene, and frames the whole payload in terms of correctifs. Minor value-add over an already rich schema.

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?

Names a specific verb+resource (structural-integrity check) and enumerates exactly what it detects: walls joining nothing, clusters outside the envelope, open roof, intersecting walls/volumes, misplaced stairs. It explicitly distinguishes itself from the sibling cao_verifier ('cao_verifier already includes it'), so an agent can tell when this narrower tool is the right pick.

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?

Opens with 'WHEN you need the structural-integrity check alone', giving the selecting condition, and names the superset alternative cao_verifier that already contains this check. Both the when-to-use and the when-to-use-something-else routing are stated, not inferred.

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

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

Annotations only carry the safety profile, and the description goes well beyond them with gating logic, exports_authorized / exports_professionnels_autorises outcomes, IFC 4 + buildingSMART + IDS validation, and the warnings_expliques requirement before a professional delivery. It is silent on permissions and on where the produced files actually land, and its 'produces deliverables' framing sits awkwardly beside readOnlyHint=true.

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: the WHEN clause and the check-first gate come before any detail, and every sentence carries a distinct fact (gate, validation, manifest contents, professional-delivery condition). It is dense and parenthesis-heavy, with some repetition around the SHA-256 'compare it with your own' remark, but nothing is padding.

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 17-parameter tool with heavy nesting and no output schema, the description usefully enumerates the manifest payload rather than leaving return values unexplained, and it covers the branch where nothing is produced. What is missing is the mechanics of delivery — where artifacts are written, their naming, and how the caller retrieves them.

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 heavy lifting is already done and the baseline is 3. The description adds little param-level syntax beyond tying `ids` to IDS validation and `warnings_expliques` to the professional-delivery flag, which is behavioural context rather than new parameter meaning.

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 ('produce the deliverables ... IFC, DXF, drawing sheet, quantities, schedules') and adds an orchestration scope that distinguishes it from the raw generators (cao_generer_ifc, cao_generer_dxf, cao_metres): it gates on cao_verifier's checks and emits a manifest. An agent can tell what it does without opening the schema.

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?

'WHEN the deliverables of a project must be produced for real' gives an explicit trigger, and the failure branch (critical alert → nothing produced, exports_authorized false) tells the agent when the tool will not do its job. It never names a sibling alternative in the same role (e.g. plain cao_generer_ifc for drafts), so the routing decision against the other producers is only implied.

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

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

Annotations already declare a safe read-only, non-destructive, closed-world profile, so the bar is lower. The description adds genuinely new behavioral context: it returns alertes[] from a geometry audit and warns to resolve critical alerts before quoting, plus notes it operates on the same scene as cao_generer_dxf. It does not describe return shape beyond the alerts array, but for a read-only tool this is solid.

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?

Three short sentences, front-loaded with the use-case condition followed by the action and the key caveat. Every sentence carries information and none is wasted.

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?

With no output schema, the description helpfully discloses one return element (alertes[]). It does not enumerate the actual quantity outputs (areas/lengths/volumes appear only in the title) or note that only murs/boites are counted, so it is slightly incomplete for a rich 12-parameter tool, but adequate overall.

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 all 12 scene parameters in detail (units, frames, defaults). The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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 ('Compute quantities (métres) from a CAO scene') and frames the outcome with a purpose clause ('FIGURES from a design — to price a job, order materials, or check a quote'). It also distinguishes itself from the sibling it shares a scene with (cao_generer_dxf).

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?

Opens with an explicit WHEN clause tying the tool to pricing/materials/quote-checking, and adds a critical-alert prerequisite ('fix critical alerts before quoting'). It clarifies its relation to cao_generer_dxf but does not name a genuine alternative tool to use instead in other situations, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), but the description adds substantial extra context: it is FREE (no API key, 0 units), returns `{categorie, libelle, cotes_defaut}`, dimensions are optional with real commercial defaults supplied, and objects propagate to the 4K visit, PDF board, DXF and quantities. Placement semantics (z is floor level, not centre) are also disclosed.

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 WHEN directive is front-loaded and the article list is compacted into category clauses. It is long and includes some narrative filler ('Until now a scene could only hold boites[]…') that pads rather than informs, but most sentences carry actionable detail.

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?

With no output schema, the description compensates fully: it documents the return object keys, the default dimension behaviour with concrete examples, placement coordinates, and downstream integration into renders/quantities. An agent has everything needed to call and use it.

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?

Zero input parameters, so per the baseline this starts at 4. The description does add useful meaning for consuming the result — placement object shape `{type, x, y, z, rotation}`, the z-is-floor-level rule, and optional dimensions with real defaults — but there are no own-parameters to clarify.

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+resource (lists the free furniture/decoration catalogue) and enumerates the ~50 modelled articles by category. It explicitly differentiates from siblings by naming what it is NOT: bare `boites[]` cuboids, and the plumbing fixtures in `plomberie[]`.

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?

Explicit WHEN clause: call it before composing `mobilier[]` and never furnish with `boites[]`. It also names the exclusion — do not duplicate plumbing fixtures declared in `plomberie[]`. The trigger condition and alternatives are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds a fidelity guarantee (figures match the IFC export exactly — same spaces, types, IsExternal flag), but it says nothing about the fact that a full scene graph must be supplied as input or about the shape of the returned data.

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?

It is front-loaded with the WHEN clause and every clause carries content — the detailed schedule inventory compensates for the absent output schema. The cost is that it reads as one very long run-on sentence rather than scannable structure.

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 12-parameter tool with no output schema, the description does well to enumerate the produced schedules, effectively standing in for the missing return-value documentation. What it omits is the input side: nothing tells the agent it must supply a complete millimetre-based scene (murs/boites/ouvertures) for this to work.

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 every one of the 12 scene-composition parameters is already documented in the schema itself. The description adds no syntax or format meaning beyond that (it references openings and marks only obliquely), so the baseline 3 is appropriate.

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 states a specific verb+resource — produce schedules (doors, windows, rooms) — and enumerates the exact contents of each schedule (marks P1/F1, sill height, clear opening width, Carrez areas, equipment counts), which is far more specific than the title. However, it never distinguishes itself from closely related siblings like cao_metres, cao_pdf or cao_devis, which an agent must pick between.

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?

"WHEN someone needs the SCHEDULES of a house design" gives an implied trigger condition, but there is no when-not guidance and no alternative tool is named. An agent reading only this description cannot tell why it should call cao_nomenclatures rather than cao_metres for quantities.

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

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

Annotations already declare readOnly/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the orange alert banner embedded when issues remain, the concrete alert examples (floating dormers, absolute sill heights), and the returned JSON shape {html, alertes, alertes_ok, resume}.

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-loads the WHEN condition, then the action, then the IMPORTANT prerequisite, then the return value. Every sentence carries information, though the alert-example parenthetical and the dxf cross-reference make it denser than strictly necessary.

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 14-parameter generation tool with no output schema, the description supplies the missing pieces: prerequisites (verifier first), failure-mode behavior (alert banner), and even the return object keys. An agent has everything needed to invoke it correctly without opening the schema.

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 all 14 parameters (walls, boxes, openings, georef, etc.). The description adds no parameter-level syntax or format detail of its own, so the baseline 3 for a fully-covered schema is correct.

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 ('Generate a professional TECHNICAL SHEET from a CAO scene') and enumerates the sheet contents (top view, elevations, shaded axonometric, MEP plan). It also distinguishes itself from siblings by noting 'Same scene as cao_generer_dxf', so an agent can route correctly.

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?

Opens with an explicit WHEN clause ('the design must be HANDED OVER to a client, an architect or a planning office') and mandates a prerequisite sequence: call cao_verifier FIRST and fix critical alerts. Both the trigger and the alternative path are stated, leaving nothing to inference.

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

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

Annotations already mark it read-only and non-destructive, and the description adds substantial behavior beyond them: which PCMI pieces are never invented, the Géoportail link condition on `georef`, the déclaration préalable thresholds, and the exact return shape (cerfa, pieces[], notice[], alertes[], avertissement with SVG drawings).

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?

Dense but well front-loaded, opening with the WHEN trigger before the mechanics. Nearly every clause carries information (regulatory references, piece names, fallbacks), though the sentence count is on the heavy side for a description that also has rich schema support.

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?

With no output schema, the description steps in by naming the returned JSON keys and noting drawings are SVG strings. Combined with the computation rules and regulatory bases, an agent has everything needed to invoke and interpret the tool correctly.

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 coverage is 100%, so the schema already documents all 15 parameters thoroughly. The description reinforces the `existant` flag semantics for extensions and mentions `georef`, but adds little beyond what the schema already states. Baseline 3 is appropriate.

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 — drafting the French permis de construire file (Cerfa 13406) from the CAO scene — and enumerates exactly which figures and PCMI pieces are produced. This clearly separates it from siblings like cao_pdf, cao_metres, or cao_urbanisme.

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?

Explicit trigger ('WHEN a detached house is headed for a BUILDING PERMIT'), an extension branch with the `existant: true` instruction, a prerequisite ('Call cao_verifier first'), and an explicit exclusion ('Local zoning rules (PLU) are NOT checked'). Routing conditions are fully specified.

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

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

Annotations mark it readOnly/non-destructive, and the description goes well beyond them: it discloses that a full single-storey scene (walls, doors, windows, named rooms, roof) is returned, that it conforms to specific French dimension rules and passes cao_verifier with zero alerts, that only single-storey is supported 'for now', and that a second layout comes back as a variant. This is substantively more than the annotations convey.

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?

It is a dense single block, but it is front-loaded with the WHEN clause and the return contract before the caveats and workflow. A few clauses (dimension list, variant mention) could tighten, but nearly every sentence carries selection or invocation value.

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?

With no output schema, the description still spells out the return payload (complete scene plus rooms/areas plus the alternate layout as a variant), the two layout options, the single-storey limitation, and the downstream toolchain. Nothing an agent needs to invoke or route this correctly is missing.

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 all eight parameters, including enums, defaults and ranges. The description mostly restates schema content (bedroom sizing, kitchen open/closed, layout types) rather than adding format or interaction detail beyond it, so the 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+resource (design/lay out a house from a brief) and explicitly contrasts it with checking or editing an existing scene, naming cao_verifier and cao_copilote. An agent can distinguish this generator from every sibling without opening a schema.

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?

Opens with an explicit WHEN condition ('asked to DESIGN a house from a brief... rather than to check or edit an existing scene') and closes with the follow-up routing: cao_copilote to retouch, cao_verifier after any edit, cao_generer_ifc or cao_permis. Both when and what-next are stated, not implied.

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description adds substantial value beyond them: it enumerates the actual computed outputs and, unusually, states hard limits — it NEVER emits Bbio/Cep/DH/Ic and those require the official Th-BCE engine. That safety/scope disclosure is exactly what prevents misuse.

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 the WHEN clause and dense but purposeful enumerations of computed quantities and exclusions. The Bbio/Cep/DH/Ic caveat earns its place; the lever/threshold tail is slightly sprawling but not wasteful.

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 13-param nested tool with no output schema, the description usefully summarizes what is returned (losses, breakdowns, design levers) and what is not, compensating for the missing output schema. Input semantics are fully delegated to the schema, which is acceptable at 100% coverage.

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 coverage is 100% across 13 parameters with rich nested descriptions, so the schema carries the parameter burden. The description adds no parameter-level guidance (units, frame, required fields) beyond what the schema already documents, so the 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 — computes thermal sanity-check indicators (envelope areas, U-values, H_T, ventilation/glazing losses) from the CAO scene — and explicitly bounds what it does NOT produce (Bbio, Cep, DH, Ic). An agent can tell this apart from regulatory or quantity tools without opening the schema.

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 'WHEN' clause gives clear pre-conditions (early thermal sanity check before the official RE 2020 study) and states when-not to rely on it (official figures need Th-BCE + a consultant). It routes conceptually but does not name a sibling tool (e.g. cao_energie) as the alternative, so context is clear yet alternatives are implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: 'Adds what is missing, never removes,' the return shape {scene, rapport, controles}, and an accuracy caveat that slab spans are 'indicative pre-design, to be validated by a structural engineer.' These go further than the annotations without contradicting them.

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 the WHEN condition and densely packed with no filler; each clause maps to a real capability. It is a single very long sentence, which makes it harder to scan, but nothing is redundant.

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 19-parameter, nested-object enrichment tool with no output schema, the description supplies the trigger, the list of generated elements, the return shape, and the hand-off to cao_generer_ifc. An agent has everything needed to call it correctly and use the result.

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 all 19 parameters and the baseline is 3. The description earns above baseline by tying the toggles to their normative sources (NF C 15-100 for electrical, 24 March 1982 decree for VMC, NF DTU 60.11 for drainage, NF EN 12831/NF EN 442 for heating), which clarifies what each switch actually enforces.

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 (completes/applies rules) and resource (structure and building services on a building scene), and enumerates exactly what it adds: lintels, strip footings, slab span check, NF C 15-100 electrical points, VMC, drainage branches, water inlet/heater, heat losses and radiators. This is unmistakably distinct from siblings like cao_generer_ifc (which consumes the output) or cao_metres.

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?

Opens with an explicit trigger: 'WHEN a building scene must be completed ... before BIM export or quoting,' and routes the agent onward ('send `scene` to cao_generer_ifc'). It does not state when NOT to use it or name a competing enrichment tool, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorld, but the description adds genuinely new behavioral facts: the render is returned inline and 'never a link', the two formats differ in output kind (SVG markup as text vs an inspectable MCP image), and nothing is drawn, saved or sent. The 'read-only' sentence partly restates the annotation, but the output-format behavior is real added context.

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 WHEN clause is front-loaded and the four short sentences each carry information (purpose, ordering vs verifier, return format, safety). The em-dash aside ('a quick visual check that the scene is what you meant') is slightly conversational filler, so it is efficient rather than maximally tight.

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 render tool whose scene schema is fully self-documented at 100% coverage, the description covers what an agent needs for selection and invocation: purpose, ordering relative to cao_verifier, and the carve-out that the image is returned inline. No output schema exists, but the two possible return kinds are explained, which closes the main gap.

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 all 13 scene parameters in depth; baseline is 3. The description contributes a small amount of extra meaning for format (svg = editable text, png = raster image) beyond the schema's enum descriptions, but says nothing about the murs/plan/boites/georef parameters it will be called with.

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 states a specific verb and resource — a top-down preview render of a CAO scene for a quick visual check — and explicitly distinguishes itself from the sibling cao_verifier ('Prefer cao_verifier before this for structured alerts'). An agent can tell what this produces (an image, not a report) without opening the schema.

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 a clear triggering context ('WHEN you want to SEE the plan before delivering it') and names an alternative with a selection rule (cao_verifier first, this second for visual double-checking). It stops short of explicit when-not-to-use guidance (e.g., when cao_pdf or cao_visite_plan is the right render target), which keeps it from a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds real behavioral context beyond them: it is 'a pre-study, never a compliance statement', and it flags professional_review_required where its checks do not calculate (structure, floors, roofs). This is useful, honest scoping that an agent can act on.

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 the WHEN trigger, followed by mechanism and return content. It is dense and the trade list is long, but every clause carries information and there is no filler. Slightly run-on but appropriately sized for a complex reviewer.

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?

There is no output schema, so the description must convey returns — and it does: alerts sorted by trade, named elements (external_id, else ifc_guid), proposed fixes, missing items, and professional_review_required flags. Combined with the 'free, no key' note, an agent has enough to call it correctly; only the input-side behavior is left to the rich schema.

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 every one of the 12 parameters is already documented in the schema. The description adds no parameter-level meaning (no mention of murs/ouvertures/boites structure or units). Baseline 3 applies when the schema does the heavy lifting.

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 states a clear verb+resource (review a design, trade by trade) and explains the mechanism: it runs cao_verifier's checks and sorts alerts into trades. It distinguishes itself from the named sibling cao_verifier by being the organizing/reporting layer. The 'revue_lots' concept is clear, though the core verb phrase is slightly abstract.

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?

Opens with an explicit WHEN clause ('a design must be reviewed trade by trade') and enumerates the covered trades. It names cao_verifier as the underlying check engine, which orients the agent toward the relationship. It does not state when to prefer this over cao_verifier outright, so it lacks a clean exclusion.

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

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

Annotations already declare readOnly/non-destructive/closed-world, yet the description adds real behavioral context: obstacles = own walls+roof plus declared masques, georef-driven site with a Strasbourg fallback that the answer announces, and a configurable time step. It notably does not describe the output format or runtime cost of a 15-parameter computation.

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 WHEN, then the returned quantities, then the caveats — a logical structure with no filler. The sentences are long and comma-dense, but nearly every clause carries decision-relevant information (inputs, outputs, limitations) rather than restating the title.

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 15-parameter, no-output-schema tool the description is unusually complete, enumerating the returned values (sunrise/sunset, max altitude, shadow area and outline, per-window hours with orientation and azimuth) and the limits. Minor gaps: the `masques` reference is not backed by a schema property, and result format/precision is unspecified.

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 100% schema description coverage the baseline is 3, but the description adds meaning beyond the schema: it explains that site/location comes from `georef` (Lambert-93), what happens when it is absent, and which params feed the computation (`annee`, `pas_minutes`, `nord_deg`). It references a `masques` input that does not appear in the listed schema properties, which weakens the mapping slightly.

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 study (sunlight hours per window, shadow on plot, obstruction by neighbours) on a named resource (the CAO scene) across three fixed dates. It clearly distinguishes itself from solar-gain/RE2020 tools by declaring what it does NOT compute, so an agent can route correctly without opening a sibling schema.

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?

Opens with the trigger condition (WHEN a design decision depends on the sun) and closes with an explicit when-not (no watts of solar gain, no RE2020 discomfort hours; those need a dynamic thermal engine), which steers the agent to a different tool. Both use and exclusion are stated, not implied.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the actual measured quantities, the shape of each check result (value, threshold, pass/fail, remediation), and two important behavioral rules: no planning value is ever invented, and without `regles` only measurements are returned. This is meaningful context the annotations cannot convey.

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 trigger is front-loaded in the WHEN clause, and the dense list of derived measurements and rule keys is functional rather than filler. It runs long, but each clause carries information an agent needs to call 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 read-only check tool with no output schema, the description adequately covers what is measured, what the result contains, and the critical requirement to supply externally-read rules. Scene-input parameters (murs, boites, plan) are left to the 100%-covered schema, which is acceptable given their shared conventions.

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 coverage is 100% so the baseline is 3, but the description adds real value by enumerating the meaningful keys accepted in `regles` (recul_voie_m, emprise_max_pct, hauteur_max_faitage_m, etc.), which the schema itself only shows as a vague example. This is genuine semantics beyond the schema.

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 action (measure the scene, then check against planning rules) and a specific resource (local French PLU rules), and its context ('before a building-permit application') separates it from siblings like cao_permis and cao_verifier. It stops short of naming an alternative tool outright, so it is clear but not maximally differentiating.

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 'WHEN a design must be checked against the LOCAL PLANNING RULES of its zone... before a building-permit application' clause gives an explicit trigger condition, and the closing line clarifies the no-rules fallback. No explicit when-not or named alternative is given, so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that, the description adds real value by naming the return shape {ok, schema_ifc4, regles, problemes} and enumerating the specific checks performed (IFC4 schema + EXPRESS rules, mm units, IfcWall material layers, named IfcSpace, thermal conductivity, storey containment).

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?

Three compact sentences: the WHEN condition is front-loaded, the scene relationship is stated, then the return contract. No wasted prose, though the return-field enumeration is slightly terse for a reader unfamiliar with the schema keys.

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?

With no output schema, the description usefully documents the return object and the validation dimensions covered, and the 12-parameter surface is fully specified by the schema. An agent has enough to know purpose, trigger and output, so completeness is strong, with only the generate-vs-validate boundary left implicit.

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 deeply nested murs/boites/toitures/georef parameters are fully documented in the schema itself. The description adds no parameter-level meaning (units, defaults, mode selection) beyond that, so the 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?

The description states a specific verb+resource ('check an IFC scene') and returns structure, and it distinguishes itself from cao_generer_ifc by noting 'Same scene as cao_generer_ifc' and the no-account condition. It stops short of separating itself from other validation-adjacent siblings such as cao_verifier or cao_conflits_ifc, so it is clear but not fully differentiated.

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 opens with a WHEN clause ('when you need to check an IFC scene without a buildingSMART account'), which implies the use case, but there is no explicit when-not guidance and no routing to alternatives like cao_generer_ifc (to produce) or cao_conflits_ifc (clash checks). Usage is implied rather than specified.

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

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

Annotations only declare the read-only/no-destroy profile, and the description goes far beyond that: it is FREE with no API key, returns {ok, erreurs_schema, alertes[...], conseils, resume}, distinguishes severite=critique blocking errors from WARNING-level ones (e.g. escalier_sans_appui), and describes the correctifs[] payloads with field-level targets. This is rich behavioral context beyond structured data, and it stays consistent with readOnlyHint=true.

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 WHEN/BEFORE clause is correctly front-loaded, but the body is an unusually long, run-on enumeration of every error code that could be tightened considerably. Much earns its place, yet the density and repeated framing ('ALSO checks…') hurt scannability.

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 12-parameter, deeply nested schema with no output schema, the description carries the return-shape burden well, spelling out the alert codes, severity semantics, correctifs structure, and the separate REST endpoints for the embedded checks. An agent has enough to call it and interpret results correctly.

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 input parameters are fully documented in the schema itself. The description adds meaning mostly about outputs/error codes rather than the 12 input params, so the baseline 3 is appropriate — it does not compensate for anything because there is nothing to compensate for.

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+resource (check/audit a CAO building scene) and immediately distinguishes itself by prescribing its position in the workflow. The agent can tell this is the pre-flight validator versus cao_pdf/cao_generer_dxf/cao_rendu/cao_visite_* generators without opening any schema.

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?

"WHEN a scene is composed and BEFORE cao_pdf / cao_generer_dxf / cao_rendu / cao_visite_plan / cao_visite_studio" gives explicit when-to-use and names the alternatives it gates. It further clarifies that fixing is a separate REST step (cao/integrite appliquer:true), leaving no ambiguity about sequencing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, yet the description still adds real behavioral context: posting the scene enables wall collision, refused steps are 'refused and explained, not silently applied', an API key is required, the 200-item action cap, and the exact return shape. Not a 5 only because it never says what happens to an existing stored view or where `depuis` state lives.

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?

It is long and laden with ALL-CAPS emphasis, but the trigger condition is front-loaded and every clause carries operational information (action grammar, scene posting, return contract). Nothing is pure filler; it is dense rather than bloated.

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 15-parameter tool with nested objects, no output schema, and a shared scene-geometry schema, the description supplies the crucial missing link — that the murs/boites/etc. parameters are there to enable collision and landmarks — plus the return contract. It is nearly complete; only the role of `reglages` and of the non-scene rooms fields is left implicit.

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 coverage is 100%, so the baseline is 3, but the description meaningfully enriches the schema: it enumerates the action vocabulary, the keyboard-shortcut aliasing ('ctrl+8' = forward, numpad as compass rose), the repeat form ('avancer x3'), the origin of `depuis`, and the purpose of posting scene fields. It does not explain `reglages`, which is the one schema block it leaves untouched.

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 states a specific verb and resource: adjust ONE camera view of a walkthrough by piloting the camera with a sequence of named actions rather than coordinates. It explicitly scopes itself against cao_visite_plan (which produces the `chemin`) and cao_visite_studio (which renders it), so an agent can distinguish it from siblings without opening schemas.

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 opening WHEN clause names the exact triggering situation ('the automatic visit is good but ONE view is wrong... rewriting a whole chemin by hand would be absurd') and names the two sibling tools to reach for instead at the relevant stages. When-to-use and alternatives are both explicit rather than inferred.

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