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

Annotations cover safety (readOnlyHint=false, destructiveHint=false) but not the rest. The description adds crucial behavior: normalized layer placement, thick walls become closed polylines (single hatchable entity), door leaves follow wall orientation, angles corner-together instead of overlapping, openings physically cut the wall with jamb, omitted lengths default-converted to the document unit, angles in degrees, response carries created handles AND failures with the offending index. This is behavior beyond both annotations and 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?

Front-loaded with the batch scope, then usage routing, then the critical wall_network rule, then default-unit behavior and return/verify. Paragraphs are purposeful; the only mild redundancy is the length-default rule stated once, which actually aids recall.

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 2-param batch tool with an enormous oneOf schema and no output schema, the description fills exactly the gaps an agent needs: element-selection routing, unit/default behavior, degree convention, and the response contract (handles + failures with index) plus a verification step. Nothing material 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 schema already documents parameters thoroughly (per-element descriptions, openings semantics, layer list, color ACI caveats). The description reinforces the most decision-critical semantics: use wall_network for walls and give it its openings, default conversion of omitted lengths, angles in degrees. Above the baseline of 3 thanks to that if/then guidance, but not fully additive.

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?

Specific verb (construit) + resource (lot d'éléments de bâtiment) with an explicit enumeration of what the batch includes (réseaux de murs, baies, portes, fenêtres, pièces, étiquettes). It explicitly positions itself against the sibling 'draw' (which 'ne connaît que la géométrie nue') and against wall/wall_run/door_in_wall/window in the Openings paragraph.

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-to-use (tout ce qui relève du plan d'architecture), when-not (draw for bare geometry), and named alternatives per element type: wall_network for walls with openings, wall_run/door_in_wall/window reserved for isolated objects. Post-call verification with render_view is also prescribed.

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 establish read-only, idempotent, non-destructive behavior, but the description adds substantial context: defect taxonomy, returned severity/location/objects/remedy, exact count with list truncation beyond 100, and the need to supply geometry because the engine only publishes bounding boxes.

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 purpose and timing, then organized into focused sections on what is examined and how thresholds behave. It is longer than strictly necessary, but nearly every sentence carries decision-relevant 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?

For a five-parameter validation tool with no output schema, the description covers inputs, expected output shape, truncation behavior, unit scaling, and workflow placement. Nothing an agent needs in order to call it correctly appears to be 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 schema documents each parameter in detail and the baseline is 3. The description still adds meaning by explaining why contours and segments must be supplied, tying them to build_structure, and noting that thresholds follow the document unit.

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, 'cherche les défauts', and a specific resource, the plan/drawing, then enumerates the defect classes it detects. This distinguishes it clearly from siblings such as build_structure and query_entities without requiring the schema to be opened.

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?

Explicitly says to call it AFTER a construction batch and BEFORE delivering a plan, making the workflow position unambiguous. It also directs the agent to supply the same points used by build_structure for the most useful check.

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 flag destructiveHint=true, but the description adds much beyond them: irreversibility, the fact that undo_last_batch will NOT restore these deletions, that handles are returned, and that an empty filter triggers a confirmation_required refusal unless the flag is set. This is exactly the behavioral context an agent needs before an irreversible call.

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 destructive/irreversible warning, then usage, then filter semantics, then the critical empty-filter confirmation rule. Length is justified given the irreversibility and the unusual empty-filter edge case; nothing reads as 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?

For a destructive 6-parameter tool with no output schema, the description covers everything needed to call it safely: what is destroyed, that it is unrecoverable, what gets returned, how filters combine, and the exact guard condition for wiping the drawing.

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 does not: filter criteria combine with logical AND, an empty filter means the entire drawing, and confirm_delete_all is only effective/required in that empty-filter case. It stops short of restating format details that the schema already carries.

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 precise verb+resource (deletes all entities matching a filter, returns their handles) and distinguishes itself explicitly from undo_last_batch, clarifying that it cancels creations only there and not here. An agent can tell it apart from siblings like query_entities or undo_last_batch 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?

Gives explicit when-to-use (remove mis-drawn geometry when undo_last_batch is insufficient or too many batches have accumulated, or clean a whole layer) and names the safer alternative workflow: use query_entities first, then delete by handles. It also states the exclusive condition for confirm_delete_all.

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 substantial context beyond annotations: batch forms a single transaction with one undo mark and one refresh; partial execution is never reported as success; the response carries both created handles and failures with the faulting index; suggests verifying with render_view. Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false), so this supplementary behavior description is strong, though it doesn't detail auth/permissions.

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?

Well front-loaded: verb+scope first, then when-to-use, then sibling routing, then unit conventions, then response shape. Every paragraph earns its place with 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?

Complete for a batch-mutation tool: covers scope, transaction/undo behavior, partial-failure reporting, and unit conventions. No output schema exists, and the description compensates by describing the return (handles + failures with index). Minor gap: does not state permission/auth requirements.

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 both parameters (label and the rich per-op item schemas). The description adds angle-unit (degrees) and length-unit context, but the baseline of 3 is correct when the schema carries the parameter burden.

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 (trace/draw) and resource (batch of geometric primitives: segments, polylines, rectangles, circles, arcs, texts, paragraphs, hatches). Explicitly distinguishes from the sibling build_structure by naming it and defining the boundary ('Pour des éléments de bâtiment... utilisez build_structure').

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 when-to-use rule: 'À utiliser dès qu'il y a plus d'une entité à tracer', with rationale (single undo mark, single refresh, chained calls slower). Also names the alternative build_structure and the condition that selects it (building elements).

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?

Les annotations confirment en lecture seule et idempotent. La description ajoute un contexte précieux : l'unité influence les longueurs futures, et la liste des calques évite les doublons. Elle ne détaille toutefois pas le format de retour.

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?

Deux phrases bien construites, sans répétition. La première décrit le contenu, la seconde donne des directives d'utilisation précises.

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?

Complète pour un outil sans paramètre et sans schéma de sortie. La description couvre l'essentiel des besoins d'un agent : quand l'utiliser et ce qu'il renvoie. Il manque juste une indication sur la structure exacte du retour.

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?

Aucun paramètre, donc base 4. La description n'a pas besoin de préciser des paramètres et se concentre sur le contenu retourné, bien que cela dépasse le cadre de la sémantique des paramètres.

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?

Il précise l'action et la ressource (décrire le document courant) et énumère les informations retournées. Cela le distingue nettement des outils voisins comme query_entities ou measure.

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?

Il donne une instruction explicite : 'À appeler EN PREMIER, avant tout tracé' et 'À rappeler après avoir ouvert un autre document'. Il indique aussi pourquoi : l'unité et les calques conditionnent les appels suivants.

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, idempotent, non-destructive), but the description adds genuinely new behavioral context: measurements are only counted for entities the engine publishes, each result carries counted/missing/complete, and totals are null rather than zero. That null-vs-zero semantics directly prevents a wrong agent inference.

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 core verb and a per-mode bullet list that maps one-to-one onto the enum, followed by usage and honesty sections. Despite its length, every block carries information for a 7-parameter, 7-mode tool; nothing is restated from the schema verbatim.

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 must carry return-value burden and does: it sketches what each mode returns (entity counts, layers, types, limits; cumulative length and area; one line per layer/type pair; nearest entities with distance). Combined with the usage and null-semantics notes, an agent has enough to select a mode and interpret 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 schema already documents all seven parameters, giving a baseline of 3. The description goes further by stating what question each mode enum value answers and by interpreting window_mode in drafting terms ("les pièces d'une zone" vs "les murs qui la bordent"), which is meaning the schema does not supply.

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?

Opens with a specific verb+resource ("Mesure et résume le dessin") and immediately states the scope ("sans l'énumérer"), which distinguishes it from query_entities. It explicitly names the two closest siblings (render_view, query_entities) and the conditions separating them.

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 when-to-use triggers ("AVANT de modifier un dessin que vous n'avez pas produit", "APRÈS un lot pour vérifier des quantités") and routes the agent to alternatives: render_view "pour voir le dessin" and query_entities "pour obtenir les handles". This is textbook when/when-not/alternative 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?

The annotations only cover safety and idempotency hints, but the description adds important behavior: missing block definitions are created automatically, existing definitions are preserved, repeated calls do not overwrite existing symbols, and the response contains created handles plus failures with the offending item index. It also tells the agent to verify with render_view.

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 purpose and usage, then moves through behavior and parameter nuances. It is fairly long and somewhat repetitive about automatic definition creation, but most sentences carry useful operational 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?

For a complex batch insertion tool with no output schema, the description covers when to use it, what it creates, how repeated calls behave, how symbols are oriented, and what the response contains. Nothing essential for correct invocation appears to be 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 already 100%, so the baseline is 3. The description still adds meaningful semantics beyond the schema, especially that each symbol has a local reference point and that wall-mounted objects use the wall as X axis with the room on positive Y for rotation_deg.

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: it inserts a list of normalized symbol occurrences in one batch. It also lists the symbol types and distinguishes the tool from draw and build_structure, so an agent can identify its role 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 explicitly says to use this tool to equip and furnish a plan after walls are placed by build_structure, and warns against making one call per object. It also names draw as the comparable alternative and explains why place_blocks is preferable.

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, idempotentHint and destructiveHint=false, so safety is covered structurally. The description still adds real behavioral context beyond that: the response is ALWAYS bounded, always returns a total count plus a truncated sample with a flag, and the guidance to refine the filter instead of raising the limit. It does not discuss permissions or error behavior, but for a local read-only query that is a minor omission.

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 paragraphs, front-loaded with what is returned and followed by usage, bounding behavior, and the sibling pointer. Each section earns its place, though the description is on the longer side for a single query tool and the bounding point is restated across two 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?

There is no output schema, so the description carries the burden of describing the return shape, and it does: handles, type, layer, color, bounding box, plus total count, truncated sample and a truncation flag. Combined with the usage and sibling guidance, an agent has everything needed to call and interpret this tool.

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 parameter is already documented in the schema, including the ACI color nuance and handle sourcing. The description adds only indirect guidance ('affinez le filtre'), not syntax or format detail beyond the schema, 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 ('Liste les entités du dessin qui satisfont un filtre') and enumerates the returned fields (handle, type, calque, couleur, boîte englobante), so the agent knows exactly what this produces. It also explicitly distinguishes itself from render_view, which serves a different need.

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 when-to-use ('retrouver ce qui existe déjà avant de modifier ou de supprimer') and states that the returned handles are a mandatory prerequisite for set_entity_color and handle-based deletion, naming those siblings. It also names the alternative for a different intent (render_view) with the condition that selects 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses framing behavior (auto-centered on content), an edge case (empty drawing yields an empty image, not an error), and a backend constraint (needs a render-capable engine; DXF yes, AutoCAD no). This is substantial context the annotations do not 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?

Front-loaded with the operation, then the usage directives, then runtime caveats. Four short paragraphs are all relevant, though the 'sans regarder, vous dessinez à l'aveugle' line is rhetorical padding rather than 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?

For a render tool with no output schema, the description covers what is returned, how the image is framed, the empty-drawing edge case, and backend prerequisites. An agent has everything needed 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% and both width/height are documented with defaults and bounds in the schema, so the description adds no parameter detail. Per the rubric, 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 specific verb and resource ('Rend le dessin courant en image PNG') plus the returned payload (image, entity count, drawing bounds). It implicitly separates itself from query/info siblings by positioning the render as the way to see what was actually drawn.

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 explicit triggers: call after every write batch, and before correcting an existing drawing. The rationale ('only way to verify what was actually traced instead of trusting a report') makes the when/when-not condition unambiguous.

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?

Ajoute beaucoup au-delà des annotations destructive=true : irréversibilité, inopérance d'undo_last_batch, liste blanche de sécurité, codes d'erreur invalid_parameter/unsupported_operation/confirmation_required, envoi tel quel sans relecture, et vérification par render_view.

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?

L'alerte destructrice est front-loadée et chaque paragraphe apporte une contrainte de sécurité ou d'usage. Le texte reste dense et long, avec quelques redondances possibles, mais rien ne semble gratuit pour un outil aussi dangereux.

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?

Sans schéma de sortie, la description couvre l'irréversibilité, les erreurs, la disponibilité selon le backend et la vérification du résultat. Elle contient tout ce qu'un agent doit savoir pour appeler l'outil correctement ou l'éviter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

La couverture du schéma est de 100 % et ses descriptions détaillent déjà casse, coordonnées, exemple et rôle de confirm_command. La description reprend surtout la liste blanche et l'exemple du schéma sans ajouter de sémantique paramètre vraiment nouvelle.

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?

Décrit précisément une passerelle vers la ligne de commande AutoCAD qui exécute une commande native sur le dessin ouvert. Elle distingue l'outil de ses voisins en nommant undo_last_batch, get_drawing_info et render_view.

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?

Donne explicitement les cas d'usage (transformations natives comme décaler, ajuster, raccorder) et les exclusions (backend DXF indisponible, commandes hors liste blanche refusées). Indique aussi de vérifier can_run_commands via get_drawing_info avant de bâtir un plan.

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=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description goes beyond them by disclosing per-handle partial-failure semantics ('la réponse indique lesquels ont été modifiés et lesquels ont échoué, avec la raison') and the 'bylayer' convention. It does not discuss permissions or reversibility, 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 core action, then purpose, then handle sourcing, then color conventions, then response behavior. Efficient, though the ByBlock/ACI 7 caveat is duplicated from the schema, which costs a little.

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 appropriately explains the return behavior (which handles succeeded/failed and why). Handle provenance, color conventions, and partial-failure handling are all covered. Minor gaps like handle-count limits are only in the schema, but that is acceptable.

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 both parameters carry detailed descriptions, so the schema does the heavy lifting. The description's color guidance ('bylayer', index 0 = ByBlock, ACI 7 = 'white') largely repeats what the schema already states, adding little beyond it. Baseline 3 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 ('Change la couleur d'une ou plusieurs entités') and scopes it precisely to entities designated by handle. It also names related siblings (query_entities, draw, build_structure) as the source of handles, so the agent can distinguish it from them 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?

Explicitly states when to use it ('corriger une entité posée sur le bon calque mais dans la mauvaise couleur, sans avoir à l'effacer puis à la redessiner') and where the required handles come from, plus the clause that handles cannot be guessed. Nothing about selection 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 flag destructiveHint=true and idempotentHint=false, but the description adds substantive behavior beyond them: only creations are undone, colour changes and deletions are NOT restored, successive calls pop batches newest-to-oldest (stack semantics), and calling with no batch fails loudly instead of silently no-op'ing. That last point is exactly the kind of failure-mode disclosure 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?

Front-loaded with the core action, then scope limits, then stack/error semantics – each paragraph earns its place. It runs slightly long for a nullary tool, but no sentence is filler given the non-obvious scope restrictions.

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 and no parameters, so the description carries the full burden and does: it covers what is reversed, what is not, ordering of repeated calls, and the failure mode. Nothing needed to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to compensate for, and the schema's additionalProperties:false confirms the no-arg contract is intentional.

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 ('Annule le dernier lot d'écriture') and immediately disambiguates by naming the exact operations it reverses ('le dernier appel à draw ou à build_structure'), plus the mechanism ('en supprimant les entités qu'il a créées'). An agent can distinguish it from delete_entities or set_entity_color 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?

Explicitly states when to use it ('dès qu'un lot s'avère faux après l'avoir regardé avec render_view') and names the alternative it beats ('c'est plus sûr que de supprimer à la main'). It also names render_view as the required verification step, 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.