Ficiel MCP

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds a nuance annotations do not cover: 'Aucune lecture, aucune écriture' — it neither fetches nor mutates, it only renders the values it is handed. That pure-presentation, no-computation behaviour is genuinely additive. It stops short of describing output structure or any rendering limits.

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 sentences with the core action front-loaded in caps ('AFFICHE UN ÉCRAN'), followed by use-case context and then the read/write disclaimer. It is appropriately sized and mostly waste-free, though the light/dark mention is a minor loose end.

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 7-parameter tool with nested objects and no output schema, the description orients the agent well on purpose and behaviour but leaves the nested parameter contracts (tableau, graphique, indicateurs.evolution) to the schema. Adequate but with clear gaps given the complexity.

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 only 14% across 7 params with nested objects, so the description must compensate — and it does name the key blocks (titre, indicateurs, tableau, graphique, conclusion). But it gives no format or constraint detail for the nested structures (row/column limits, graph type enum, evolution object), and 'en clair ou en sombre' alludes to a theme option that has no corresponding schema property, adding mild ambiguity.

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: it renders ('met en forme') an already-computed analysis into a Ficiel-styled screen, and enumerates the rendered blocks (titre, indicateurs, tableau, graphique, conclusion). The phrase 'analyse déjà calculée' and 'ne calcule rien' clearly separates it from sibling compute/read tools such as ficiel_synthese or ficiel_get_stats.

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 concrete context ('analyse sur mesure faite de plusieurs lectures : résultats par message d'ouverture, comparaison de comptes ou de séquences, résumé de compte'), which tells the agent when this tool is the right fit. It stops short of naming an explicit alternative or a when-not condition, so it is a clear context rather than full routing.

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 destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: the six guard checks (blacklist, protected stage, blocking tag, channel pause, follow-up cap, spacing), the fact that a refusing guard leaves the card pending with a reason, the pre-send identity comparison against the real contact, and the required write scope. This is exactly the behavioral disclosure an agent needs before an irreversible send.

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 send action in caps, and nearly every clause carries operational information (guards, preconditions, scope). It is a dense run-on paragraph rather than structured sentences, which slightly hurts scannability but wastes 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?

For a destructive, non-idempotent send with no output schema, the description covers failure behavior (card stays pending, reason returned), preconditions and required scope. It does not say what a successful approval returns or whether the send is confirmed synchronously, which is the remaining 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%, and the schema's own recipient description already spells out the case/accent-insensitive comparison, the "sans nom" convention, and the recipient_mismatch refusal. The description restates recipient's mandatory status and edited_text's 4000-character limit without adding new syntax or format meaning, 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?

Opens with a capitalized verb+resource ("ENVOIE le message d'une carte de relance") and specifies the mechanism (the app's single send path, origine kord_card) and the target (a real contact, on behalf of the organization). This clearly separates it from ficiel_reject_card, ficiel_defer_card and ficiel_list_pending_cards, so an agent can route correctly 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?

Gives clear context: the card must belong to the intended conversation, recipient must come from what ficiel_list_pending_cards returns, and text cards only. It stops short of naming the alternative actions (reject_card/defer_card) or stating when not to approve, so the routing guidance 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 only declare write/idempotent/non-destructive; the description adds the real behavioral facts: the state-gate (rules outside the expected state are left untouched), the return value (count of updated rules), and the required 'write' scope. This is exactly the context an agent needs before mutating state.

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 action and starting state, then the sibling alternative, then the partial-failure semantics and return value. 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?

For a single-parameter mutation with no output schema, the description covers the precondition, the effect on Kord's follow-ups, the non-matching-rule behavior, the return value, and the auth scope. Nothing an agent needs to call it safely 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 single parameter is already documented as pattern_id UUIDs with a pointer to ficiel_list_learned_patterns. The description adds no further meaning about the parameter (e.g. batch limits or ordering), 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 (active/adopte) and resource (règles apprises proposées par Kord), plus the starting state 'proposed'. The sibling it is not — ficiel_dismiss_learned_patterns — is named directly, so an agent can distinguish the two 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?

Names the alternative (dismiss) and its effect, and gives a precondition: only rules in the expected 'proposed' state are touched, others are skipped. That is close to explicit when/when-not guidance, though it never states a positive trigger scenario beyond the implied 'a rule is proposed'.

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 annotations: states reversibility, that no message is sent, that nothing is deleted, that an archived conversation auto-returns on the contact's next message, that a no-op returns 'already_in_state', and that a 'write' scope is required. Annotations already cover destructiveHint=false and idempotentHint=true, but the description adds the concrete consequences 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-loads the effect ('Sort la conversation de la boîte de réception') and then packs the auto-return rule, reversibility, no-op behavior, and permission requirement into a few dense clauses without repetition. Every sentence adds a distinct fact.

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, yet the description still discloses the meaningful response signal (already_in_state), the reversibility semantics, and the required scope. Nothing an agent needs in order to call this mutation safely and interpret the result 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?

Only one parameter, conversation_id, with 100% schema description coverage, so the baseline is 3. The description adds no syntax or format information beyond what the schema provides; the only extra hint is that the conversation may be 1:1 or group.

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 ('Sort la conversation de la boîte de réception') and clarifies it applies to both 1:1 and group conversations. It explicitly names the inverse sibling, ficiel_unarchive_conversation, so an agent can distinguish archive from unarchive without reading 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?

Names the counter-tool (ficiel_unarchive_conversation) and explains the automatic-return condition (next inbound message), which effectively tells the agent when archiving is appropriate versus permanent removal. It does not mention the bulk variant ficiel_bulk_archive as an alternative for multi-conversation cases, so guidance is clear 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?

Goes well beyond the annotations: discloses the just-in-time re-verification of slot availability, the exact refusal behavior and its cause (Calendly paid plan/email), the side effect on the record ('RDV pris' with date), and explicitly that no message is sent. This is the kind of 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?

Front-loads the core action and keeps every sentence functional (input source, re-verification, preconditions, success effect, no-message constraint, scope). It is dense but not padded; a slightly tighter phrasing on the refusal clause would improve it.

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 covers the resulting state (appointment created, record moved to 'RDV pris' with date) and the no-message behavior. For a 3-parameter mutation tool, 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 coverage is 100%, so baseline is 3, but the description adds real meaning: email is required by Calendly and falls back to the contact's record if omitted, and start must be exactly the value returned by ficiel_get_slots. This clarifies dependency and fallback logic not expressible in the schema alone.

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 (réserve) and resource (le créneau qu'un contact a ACCEPTÉ) within the connected calendar, and names the sibling that produces the input (ficiel_get_slots). An agent can distinguish it from ficiel_mark_booked or ficiel_schedule_message 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?

Makes the selection condition explicit: the slot must be one the contact accepted, sourced from ficiel_get_slots. It also states refusal conditions (missing email, no paid Calendly plan) and the write scope. It stops short of naming the sibling to use instead (e.g. ficiel_mark_booked) when booking isn't possible.

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 disclose destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context: that it requires 'write' scope and that the cancelled message 'n'existe jamais pour le contact', clarifying the observable effect (no trace for the contact) beyond the annotation flags.

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, zero filler, with the action and its pending-state constraint front-loaded before the scope and effect notes. 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?

For a one-parameter, no-output-schema mutation with rich annotations, the description covers action, precondition, scope, and user-visible effect. It stops short of stating error behavior for a non-pending or unknown schedule_id, which leaves a small 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 coverage is 100% and the single parameter already documents its UUID format and points to ficiel_list_scheduled as the source of the ID. The description adds nothing further about the parameter, 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 ('Annule un message programmé') and constrains it with 'encore en attente', which cleanly separates it from ficiel_list_scheduled and ficiel_schedule_message. An agent immediately understands this cancels, not lists or creates.

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 phrase 'encore en attente' gives a clear applicability condition, and the required 'write' scope is stated, so the agent knows when it can and cannot be used. It doesn't explicitly name a fallback for already-sent or already-cancelled messages, but the pending-state qualifier covers the main routing decision.

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?

Touches every behavioral trait that matters beyond the annotations: an existing pending follow-up is reused as-is (matching idempotentHint), otherwise a draft is generated and billed against the monthly conversation quota, `text` is display-only and never persisted, no message is sent, and a stale draft is marked replaced rather than erased. There is mild tension with destructiveHint=true since the text says 'rien n'est supprimé', but the description's 'marqué remplacé' explains the mutation model rather than contradicting it.

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 long (six sentences) but densely front-loaded: the widget purpose and its contents come first, followed by state-reuse, billing, the `text` caveat, and the no-send/no-delete guarantees. Each clause carries a distinct behavioral constraint, so there is little filler despite the length.

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 describe what the agent gets back — and it does, listing the card's rendered elements (dernier échange, raison de relancer, texte modifiable, boutons). Combined with annotations and full schema coverage, an agent has everything needed to invoke this 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% (baseline 3), and the description still adds real meaning: it clarifies that `text` overrides Kord's wording only in the rendered card, is not saved, and does not replace the underlying draft — a semantic distinction the schema field alone does not convey. conversation_id semantics are covered by the schema's cross-references to sibling tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('AFFICHE UN WIDGET : la relance préparée par Kord pour UNE conversation') and immediately enumerates the card's content (contexte, texte modifiable, boutons Envoyer / Ne plus proposer). It implicitly separates itself from ficiel_envoyer_relance by stating the send only happens on the user's click, so an agent can tell what this tool does and does not do.

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 only implied: the agent can infer this is the tool that surfaces/prepares a follow-up card for one conversation, and that ficiel_envoyer_relance handles actual sending. However, no sibling (ficiel_envoyer_relance, ficiel_prepare_followup, ficiel_ne_plus_proposer) is named as an alternative, and no explicit when-to-use / when-not-to-use condition is given.

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 is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description usefully adds that it is the widget/fiche button gesture (single-lead scope), but says nothing about side effects such as automation or relance triggers firing on a stage change, and no output schema exists.

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, tight sentence with no filler; only minor deduction because it front-loads the UI gesture context ahead of the actual action verb.

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 simple two-parameter mutation with annotations covering idempotency and destructiveness, the description is minimally adequate. It is nonetheless incomplete on the two things an agent most needs: what it returns / what changes as a side effect, and how it differs from set_stage and bulk_set_stage.

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 only 50%: 'stage' is documented as a stage_key while 'lead_id' carries no description (only format: uuid). The description's phrase 'une autre étape du pipeline' restates the concept without adding key syntax, valid values, or how to obtain a stage_key (e.g. via list_tags_and_stages), so it fails to compensate for the gap.

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 and resource: it moves the contact ('passe le contact') to another pipeline stage. However, it never distinguishes itself from the clearly overlapping siblings ficiel_set_stage and ficiel_bulk_set_stage, so an agent cannot tell from the text which of the three stage-changing tools applies.

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 only usage signal is the UI framing ('Geste du bouton Changer d'étape de la fiche'), which implies it is the single-lead, record-view action, but this is left to inference. There is no when-to-use, when-not-to-use, or explicit routing against set_stage / bulk_set_stage, the obvious 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?

Annotations already declare read-only, idempotent, closed-world, non-destructive. The description adds genuine behavior beyond them: it renders a screen (AFFICHE UN ÉCRAN) rather than returning a plain data payload, and it discloses a guardrail that the window never reaches back before the organization's signup. It does not, however, describe rate limits or the exact delta format.

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, front-loaded with the most important behavioral fact (that it displays a screen) followed by what is compared and the signup-boundary constraint. 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?

For a one-parameter, read-only, idempotent tool with full schema coverage and no output schema, the description adequately conveys the comparison semantics (before/after per indicator, with deltas) and the signup-boundary rule. Minor gap: it leaves the exact returned structure somewhat implicit in the 'écran' phrasing.

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 single parameter period_days is already documented in the schema with its default and bounds. The description restates its meaning as 'period_days derniers jours' but adds no syntax or edge-case detail beyond the schema, so the baseline of 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?

State a specific verb (compare) and resource (current period vs. immediately preceding equivalent period, with deltas), plus a concrete detail that each indicator is shown before/after. It distinguishes itself reasonably from point-in-time siblings like get_stats, but 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?

Usage is only implied: an agent infers it should call this when a period-over-period comparison is wanted. There is no explicit when-to-use statement, no exclusion, and no reference to alternatives such as ficiel_get_stats or ficiel_synthese that also expose metrics.

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 annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by disclosing that quiet hours no longer block any send since 08/09/2026 and only shift morning-batch preparation time (7h30 local default), that write scope is required even for reads, and that paused=false is a locked product path that always refuses while paused=true works normally. These are non-obvious operational facts an agent cannot derive from structured fields.

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 core purpose is front-loaded in the first clause, with the caveats (ATTENTION quiet hours, IMPORTANT locked pause) signposted afterwards. It is dense but each block carries distinct information; only the amount of emphasis formatting keeps it from being 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?

A mutation tool with no output schema and 100% schema coverage needs the description to carry behavior, scope and side effects — and it does: locked paths, required scope, timing side effects of quiet hours, and the read-only alternative. 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%, so the schema already documents channel enum, paused, quiet_start and quiet_end. The description mostly restates the quiet-hours semantics already in the property descriptions; its only marginal addition is the 'verrou produit' framing for paused=false, which the schema itself points back to. 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?

Opens with a specific verb+resource: 'Lit ou modifie les réglages de délégation Kord d'un canal entier (Instagram, WhatsApp…) : mise en pause, et heures calmes.' It names exactly what is configured (pause, quiet hours) and names the sibling that covers the read-only case (ficiel_list_tags_and_stages), so an agent can separate it from other config tools 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?

Explicit routing: use this tool for read or write with a write-scope key, and use 'les champs ai_master_enabled/quiet_start/quiet_end de ficiel_list_tags_and_stages' for a read-only key. It also states the when-not case (paused=false always refuses) so the agent knows a path that will never succeed.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds real context beyond that: the appended text is user-visible and editable, the rule is deleted from the learned list, non-conforming rules are left untouched, and the return value ('updated' count) plus the write-scope requirement are disclosed. Only the atomicity/partial-failure semantics of a multi-id call remain unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action, with no redundant padding; each clause carries a distinct fact (what is written, what is removed, precondition, return value, scope). Slightly dense but efficient for a mutation with a precondition.

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 and a single fully documented parameter, the description still supplies the pieces an agent needs: the destination of the migrated text, the removal side effect, the state precondition, the returned count, and the required write scope. An explanation of partial success behavior when some ids fail would fully close the 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 pattern_ids (uuid array, 1-100 items) and its link to ficiel_list_learned_patterns are already documented in the schema. The description adds no format or selection detail 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 compound verb (append rule text to Kord's custom instructions, then remove them from the learned-rules list) and names the exact resource. It cross-references ficiel_edit_agent_prompt and ficiel_list_learned_patterns, so an agent can place it among the other learned-pattern siblings without opening their 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?

Usage is implied: the description explains what the operation does and where the resulting instructions can be read/edited, and the precondition (a rule not in the expected starting state is untouched). However it never states when to choose this over the close siblings ficiel_approve_learned_patterns, ficiel_dismiss_learned_patterns or ficiel_ne_plus_proposer, leaving the routing decision 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?

Beyond the annotations, the description discloses that no message is sent, the card leaves the current batch, the contact returns on the return date, and the deferral can be cancelled in the app. These details clarify the write behavior and reversibility in a way that annotations alone do not.

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 core action and duration, then adds relevant behavioral details. It is mostly efficient, though the enum/default repetition and phrase “sans jugement” make it slightly less tight than it could 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?

The definition is complete for a write operation with fully described parameters and no output schema: it covers the action, duration, return behavior, text-card restriction, lack of sending, cancellation path, and required write scope.

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 both parameters are already documented in the input schema. The description repeats the allowed `jours` values and default, but does not add new meaning for `card_id` beyond identifying it as a follow-up card.

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 action and resource: putting the contact of a follow-up card aside for a number of days. It also distinguishes this from sending a follow-up by explicitly saying “Rien n'est envoyé” and limits scope with “Cartes texte seulement.”

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context by comparing it to “Reproposer plus tard” in the app and specifying that only text cards are eligible. However, it does not explicitly name sibling alternatives such as sending, approving, or rejecting a card, so the agent must infer when to choose deferral rather than another card action.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description adds real beyond-schema context: which states are eligible, that out-of-state rules are left untouched (partial-failure semantics), that the modified count is returned as 'updated', and that a write scope is required. This is substantive behavioral disclosure.

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 verb and scope lead the sentence, followed by state preconditions, side effect on untouched rules, return value, and auth requirement. Dense but front-loaded and free of filler, though it packs several clauses into long 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 single-param mutation tool with no output schema, the description covers eligibility states, no-op behavior for ineligible rules, the returned count, and the required write scope. An agent has everything needed to invoke it correctly 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 description coverage is 100% and the single param (pattern_ids) is well documented in the schema itself, including a pointer to ficiel_list_learned_patterns. The description adds no parameter-level detail, so the baseline 3 for schema-driven param semantics 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 ('Écarter' = dismiss/discard) and resource (règles apprises) and clarifies the effect ('Kord ne les suit plus'), which is far more informative than the title. It does not explicitly name a sibling (e.g. ficiel_approve_learned_patterns or ficiel_convert_learned_patterns), so differentiation is inferable from the state semantics rather than stated.

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?

Implies usage by describing the affected starting states (proposed, approved) and the outcome, which tells an agent when the call will take effect. However, it never states when to prefer this over approve/convert/reject siblings, nor any exclusion beyond the implicit state precondition.

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 annotations (destructiveHint, idempotentHint, readOnlyHint=false) with concrete behavioral rules: partial updates ('Seuls les champs fournis changent'), list replacement semantics, hard rejection of over-long text ('REFUSÉ, jamais coupé'), immediate prompt recompilation, automatic version creation, and the required 'write' scope. This is the kind of operational detail an agent cannot infer from structured fields.

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 purpose and behavioral rules, and every sentence carries information. It is long, however, and enumerating all 21 fields overlaps heavily with the schema, which a leaner definition could omit.

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 21-parameter, all-optional mutation tool with no output schema, the description supplies the missing context: replacement semantics, validation behavior, versioning side effects, auth scope, and the sibling to use for prompt-only edits. Nothing needed to invoke it correctly appears 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema states only locally: list fields replace the whole list, and remove_sources is validated atomically. It also glosses the closing_action and tone_preset enums in prose, adding marginal value over 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 precise verb and resource ('Modifie le profil STRUCTURÉ de Kord, comme l'écran de configuration, champ par champ') and enumerates the editable fields, so the agent knows exactly what this mutates. It explicitly distinguishes itself from the sibling ficiel_edit_agent_prompt ('Les instructions libres ne sont pas touchées').

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?

Clear context for use (structured profile editing, field by field) and it routes to alternatives: ficiel_edit_agent_prompt for free instructions, ficiel_list_agent_config_versions / ficiel_restore_agent_config_version for versions. It does not state when NOT to use it beyond that boundary (e.g., relationship to ficiel_get_agent_config for reading first), 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false. The description goes well beyond them: it requires 'write' scope, guarantees the full text is never overwritten, mandates that each search find EXACTLY one occurrence, and states the call is refused (not-found/ambiguous) rather than guessed. Those are precisely the failure modes an agent must anticipate.

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 purpose, then ordered constraints (scope, matching rule, append rule, fallback routing). Every sentence carries distinct operational information 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?

For a destructive 1-parameter mutation tool whose annotations already cover the safety profile, the description supplies the remaining essentials: scope requirement, non-overwrite guarantee, exact-match rule, append behavior, and where to go when no match exists. No output schema is needed to complete 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 coverage is 100%, so the baseline is 3. The description adds real meaning: operations run in order, an operation's 'search' must match exactly once, and an operation without 'search' is appended to the end. That clarifies matching and append semantics beyond the field descriptions.

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 verb and resource: applies search/replace or append operations on the organization's custom_instructions text. It distinguishes itself from ficiel_edit_agent_profile by noting that structured-profile settings (e.g. tutoiement/vouvoiement) are NOT edited here, so an agent can route correctly 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?

Gives clear when (search/replace on free-text instructions) and when-not (settings that live in the structured profile belong to a different mechanism/Ficiel configuration). It doesn't name ficiel_edit_agent_profile directly, leaving the alternative tool implicit, but the routing context is explicit 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?

With annotations already declaring non-read-only, destructive and non-idempotent, the description still adds substantial context: sends go through the same guarded path as card validation (verified recipient, blacklist, 'Ne pas contacter', natural short delay), the call only returns a message id, and real delivery status must be read asynchronously via ficiel_statut_envoi. That is exactly the async/side-effect nuance an agent needs before firing a non-idempotent send.

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 action is front-loaded and the two sentences carry no filler; the guarded-path parenthetical is dense but informative rather than redundant. Slightly long single sentence, but each clause (path, checks, return, status lookup) earns its place.

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, and the description correctly covers the return value (message id) plus where the real outcome lives (ficiel_statut_envoi), along with the compliance checks and natural delay. It stops short of covering failure behaviour or the default when text is omitted, which are the remaining gaps for a destructive, non-idempotent send.

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 only 33% (recipient documented), so the description must compensate. It clarifies that text is optional and may be the card's text modified or not, and that the send targets 'le contact de la carte', reinforcing the recipient/card_id linkage. card_id itself is still not explicitly defined, keeping it short of a 5.

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 ('envoie le texte ... au contact de la carte') and frames itself as the widget Send button of the relance card, which sets it apart from generic sending siblings. It does not explicitly contrast with the closest neighbours (ficiel_decide_card, ficiel_prepare_followup, ficiel_send_message), so an agent must infer the boundary, but the resource and scope are unambiguous.

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 implied by 'Geste du bouton Envoyer de la carte de relance' — it is the action taken from a relance card — and it routes the agent to ficiel_statut_envoi for the outcome. There is no explicit when-not-to-use or statement of which sibling to prefer for plain outbound messaging (send_message) or for card decisions (decide_card).

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 the safe read-only, idempotent, non-destructive profile, and the description adds real context beyond that: what the widget displays, that it carries Préparer une relance / Changer d'étape / Voir dans Ficiel buttons, and how it resolves ambiguous person matches. It stops short of noting any auth or visibility constraints, but for a read-only view this is solid added value.

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 core action is front-loaded ("AFFICHE UN WIDGET") before the parenthetical field list, so an agent can stop reading early and still know the tool's purpose. The long enumeration of widget contents is dense but earns its place by telling the agent what to expect on screen; 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 read-only widget tool with no output schema and only 3 parameters, the description covers what the agent needs: what is shown, the action buttons available, and how to supply the identifier plus the ambiguity fallback. The main missing piece is explicit routing against lookalike siblings such as ficiel_get_lead.

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 only 33% (only contact is documented, as pseudo/nom/numéro). The description compensates partially by restating the three identification keys and clarifying that any one of them identifies the person and that contact accepts pseudo, name, or number. It does not state precedence when several are supplied, nor that all three parameters are optional despite 0 being required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ("AFFICHE UN WIDGET : la fiche d'une personne") and enumerates exactly what the widget contains, so the agent knows precisely what it produces. It implicitly distinguishes itself from data-returning siblings like ficiel_get_lead by being a widget view with action buttons, but never names those siblings or contrasts against them 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?

It gives useful operational guidance on identifying the person (conversation_id, lead_id, or contact) and what happens on ambiguous matches (a list of lead_id to choose from). However it never states when to reach for this tool instead of ficiel_get_lead, ficiel_get_lead_context, or ficiel_get_conversation, leaving the choice 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: it explains exclusion rules (blacklist, groups, excluded stages, paused contacts, channel connected) and sorting order, which helps the agent understand what results will contain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized: it defines dormant leads, specifies exclusion rules, and states sorting order. The opening fragment 'Données sans écran.' is somewhat cryptic and could be clearer, but the rest is front-loaded and information-rich without redundant repetition.

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 list tool with no output schema, the description provides adequate completeness by specifying the cohort, exclusions, and ordering. Pagination behavior is documented in the input schema, so the description does not need to repeat it; however, it does not describe return fields, which would have been helpful absent an 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?

With 100% schema description coverage, the baseline is 3. The description reinforces the meaning of silence_days in the filtering condition, but adds no syntax or format details for limit, stage, or cursor beyond what the schema already documents.

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: finding dormant contacts who have replied at least once, to whom you wrote last, and who have been silent for more than silence_days days. This clearly defines the tool's purpose, but it does not name or distinguish from sibling tools such as ficiel_search or ficiel_envoyer_relance.

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 implied by the detailed definition of dormant leads and the comparison to Ficiel's 'à relancer' selection. However, there is no explicit guidance on when to prefer this tool over alternatives like ficiel_search or ficiel_get_lead, nor are there any exclusions or prerequisites stated.

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 readOnly, idempotent and non-destructive, so the safe-read profile is known. The description adds real value beyond that: it warns the output is complete and untruncated ('chaque texte en entier') and flags a read-only field that cannot be modified here, which prevents a misuse attempt.

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?

Long single sentence, but front-loaded with the key claim ('Lit TOUTE la configuration... chaque texte en entier') before the field list. The enumeration is dense yet justified because there is no output schema to carry it; structure could be improved with a bulleted list but nothing 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 carries the burden of describing the return payload and does so exhaustively, including the caveat about the read-only compiled prompt. Combined with annotations covering the safety profile, 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?

The tool takes zero parameters, so the baseline is 4. The enumeration of configuration fields describes return content rather than inputs, which is informative but not parameter semantics per se.

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 ('Lit TOUTE la configuration de l'agent') and then enumerates exactly what constitutes that configuration, from niche to compiled prompt. An agent can immediately distinguish it from ficiel_list_agent_config_versions (versions) and the edit tools 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?

No explicit 'use when' clause, but the description routes the agent correctly by naming ficiel_edit_agent_prompt as the tool that targets the free-text zone and ficiel_edit_agent_profile as the only way to change the compiled prompt. This clarifies read-vs-edit boundaries, though it never states a trigger condition for calling this tool.

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 non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: all touched contacts are listed from most recent to oldest and paginated via next_cursor. It does not cover rate limits or auth needs, but those are less critical for a read-only history tool.

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 short, front-loaded with the core purpose, then flows into returned metrics and list/pagination behavior. Every sentence carries information, though the all-caps 'AFFICHE UN ÉCRAN' phrasing is slightly unusual.

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 and four input parameters, the description adequately characterizes the return: send/response metrics, contact counts, response rate, a listing of all touched people in reverse chronological order, and pagination. It does not describe edge cases such as empty histories, but it is otherwise sufficient for correct invocation.

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 fully documents days, limit, cursor, and recipe_id. The description reinforces the time window and pagination concept, but adds no syntax, format, or constraint detail beyond what the schema provides, which matches the baseline of 3.

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 displays the execution history of an automation, including sends, responses, contact counts, and response rates over a time window. It also distinguishes itself from the sibling ficiel_get_automations by referencing that tool only for obtaining the recipe_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool returns but gives no explicit guidance on when to use it versus alternatives such as ficiel_get_stats or ficiel_get_automations. The only reference to a sibling is for retrieving a required parameter, not for selecting this tool.

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 the safety profile is covered. The description adds genuinely new behavioral context: the automations are human-authored verbatim and never generated at send time, which tells the agent the listing content is static and not dynamically produced.

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 compact sentence that front-loads the resource, then the returned fields, then the behavioral note. No wasted clauses.

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 enumerates the returned fields (activation, contenu, état), which is what an agent needs for a zero-param getter. It stops short of describing ordering, pagination or volume, but for this simple read that is a minor 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond the schema; baseline of 4 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 recettes d'automatisation de votre organisation') and concretely enumerates what is returned (activation, contenu, état) plus what the objects are (commentaire vers message privé, relance après silence). It clearly contrasts with the write-side siblings create_automation and set_automation, though it does not name 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?

The read-only listing intent is implied by 'Liste', which makes it distinguishable from create_automation/set_automation, but there is no explicit when-to-use or when-not-to-use guidance and no alternative (e.g. get_automation_runs) is mentioned for run history.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description is free to add scope detail instead: it discloses that contacts with no Ficiel conversation are included, and that results are paginated with an exact total. That inclusion rule is genuinely non-obvious behavioral 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?

Two dense sentences with the scope stated first and pagination last; nothing is padded. Minor awkwardness in the repeated 'quand quand' and the return-shape hint is compressed, but it is appropriately sized.

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 has to carry the return semantics, and it does name the three things an agent needs: who is blacklisted, since when, and the pagination/total fields. It stops short of describing the full record shape, but is complete enough for correct invocation.

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 (limit, cursor) are documented in the schema, so the baseline is 3. The description reinforces cursor-based paging via next_cursor but adds no syntax or constraint information beyond what 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?

The description states a concrete resource (les contacts en liste noire) and the returned attribute (depuis quand), so an agent knows this is the read-only view of the organization blacklist. It does not explicitly name the sibling ficiel_blacklist_lead as the mutation counterpart, so differentiation is left implicit.

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 implied rather than stated: the tool is the only list-style reader among the blacklist siblings, but the description never says when to reach for it versus ficiel_blacklist_lead or ficiel_ne_plus_proposer. No exclusions or prerequisites are given.

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), and the description adds real context beyond them: owner-only authorization, refusal during the free audit and for suspended organizations, and units in centimes. It repeats 'Lecture seule' which the annotations already declare, but the auth and state preconditions are genuine additions.

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 that front-loads the key concept (the two cash numbers) before elaborating. Every clause carries domain meaning (null semantics, ×5% estimate, centimes) though 'Lecture seule' is redundant with the annotations and the paragraph runs long.

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 carries the return-value burden and does explain the two figures, the null conventions ('null = à renseigner, jamais 0'), units in centimes, and the estimate formula. It omits pagination/response shape but is otherwise complete enough to call 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 limit (default 50, max 200, totals always span all rows) and cursor (next_cursor) are already fully documented. The description adds no syntax or format detail for the two parameters, 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 ('AFFICHE UN ÉCRAN cash signé et dormant') and immediately defines the two figures it reports so an agent knows exactly what it renders. It explicitly differentiates its large dormant-cash definition from the sibling ficiel_find_dormant_leads, so the boundary is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this screen is usable (owner-only; refused during free audit and for suspended orgs) and implicitly when not to reach for it by contrasting against ficiel_find_dormant_leads. However it never states the positive use case ('call this when...') or names other candidate tools, so no explicit when/when-not routing.

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 the safety profile is covered. The description still adds real value beyond them: it explicitly reassures that no import is triggered from this call and documents default/limit behavior for retrieval history (5 by default, up to 100 with passes), which an agent cannot infer from the annotations 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?

Everything is packed into one very long parenthetical sentence, which is dense and poorly front-loaded; the core 'what it returns' is buried mid-clause. No wasted words in the sense of filler, but the structure hurts 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?

For a read-only tool with no output schema, the description does a good job describing the shape of the returned data (per-account state, last activity, retrieval progress, recent retrievals with conversation/message counts). Combined with full annotation and schema coverage, 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%, so the baseline is 3. The description confirms the two filter axes (channel, account_id) and the passes window ('5 par défaut, jusqu'à 100'), but adds no syntax or edge-case meaning beyond what the schema already documents.

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 resource (per connected account: channel state, last activity, history retrieval progress) and enumerates what is returned, so an agent can tell it apart from siblings like ficiel_get_stats_by_channel. It is clear but slightly diffuse, being delivered as one long enumerative sentence rather than a crisp verb+object statement.

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 states the key constraint 'Lecture seule : aucun import n'est déclenché d'ici' and that results are filterable by channel or account, pointing to ficiel_list_tags_and_stages as the source of account_id. However, it never says when to choose this over related status/stats tools, so usage 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 declare readOnly/idempotent/non-destructive, and the description adds genuine behavioral detail: 50-per-page sorting and cursor direction ('next_cursor pour remonter dans le passé'), full voice transcription semantics, and the meaning of transcription_status/transcription_reason failure states. It stops short of stating error behavior for an unknown conversation_id.

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 core purpose and return shape, then qualifies voice transcription and group handling. Slightly dense and repetitive ('COMPLÈTE (aucune coupure, tous les caractères)'), but every sentence 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?

With no output schema, the description does the heavy lifting on return content (contact card, messages, voice fields, per-message author for groups) and covers it well. It omits what happens on invalid or missing conversation IDs, which is the main remaining 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 baseline is 3. The description says '50 par page' and maps the cursor to next_cursor, but this essentially restates the schema's own descriptions of limit and cursor without adding new 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 precisely what is returned: a complete conversation with the contact card and messages, ordered newest-to-oldest, 50 per page. An agent can tell this is the single-conversation reader versus the sibling ficiel_list_conversations 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?

Usage is implied by the scope (one complete conversation, paginated) but there is no explicit when-to-use statement or named alternative such as ficiel_list_conversations for browsing, or ficiel_get_lead for contact-only data. The pagination note hints at context but no exclusions are given.

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, destructiveHint=false and openWorldHint=false, so safety is covered. With no output schema, the description usefully carries the return burden: six stages plus the share of the previous stage, response rate and booking rate, which tells the agent what it will receive. It doesn't cover pagination or latency, but that is not needed for a fixed-shape read.

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 sentence with the key action front-loaded in caps ('AFFICHE UN ÉCRAN'), followed by the stage list and the derived metrics. Nothing is wasted, though the stage chain with parenthetical 'critères écrits pour Kord' is somewhat heavy for one 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?

For a two-parameter, zero-required, read-only analytics tool with 100% schema coverage and no output schema, the description supplies the missing return-shape information (stages, share-of-previous, response/booking rates) and the channel scope. It is complete enough to invoke correctly, with only the sibling-routing gap remaining.

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 both parameters (channel enum and period_days). The description adds meaning by clarifying 'tous canaux ou un seul' (channel is optional, all channels by default) and that the period applies to the funnel, going slightly beyond the schema's raw field definitions.

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 (affiche) and resource (l'entonnoir de conversion) and enumerates the six funnel stages, so the agent knows exactly what it produces. It situates itself against the Stats screen ('l'entonnoir de l'écran Statistiques, mêmes chiffres'), giving partial sibling differentiation versus ficiel_get_stats, but does not name any sibling tool directly.

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 context is implied by the analytics framing (period-based funnel figures), but there is no explicit when-to-use or when-not-to-use guidance relative to siblings like ficiel_get_stats, ficiel_get_stats_by_channel, ficiel_compare_periods or ficiel_synthese. The agent must infer which analytics tool to pick.

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. The description adds genuinely useful behavior beyond that: notes are ordered newest-first in pages of 20, and notes_next_cursor fed back via notes_cursor continues the listing. It does not state what happens for an unknown lead_id, but the pagination contract is a real addition.

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 screen-rendering purpose is front-loaded in the first clause, followed by the field inventory and then pagination. It is dense but every clause carries information; the pagination sentence runs slightly long and the all-caps emphasis ('EN ENTIER') is stylistically noisy 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?

With no output schema, the description carries the return-value burden and does so by listing the returned fields and the notes pagination model. Combined with the read-only annotations, an agent has enough to call and interpret it; only error/empty-lead behavior is 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 coverage is 100%, so the baseline is 3; the description goes further by explaining the cross-call cursor loop (notes_next_cursor from the previous call goes into notes_cursor) and that notes_total reports total volume, which the schema alone does not convey. It adds little on notes_limit beyond the schema's own default/max.

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 — it displays the full record (fiche) of a contact — and enumerates what the record contains (identity, channels with read state, stage, tags, notes, message counters, last contact). An agent knows it retrieves one lead's complete profile. However, it never distinguishes itself from the very similar siblings ficiel_fiche_prospect, ficiel_get_lead_context and ficiel_get_lead_by_handle, which all sound like the same retrieval.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named, despite three near-identical lead-lookup tools in the list. Usage is only implied by the enumerated content (use it when you need the whole picture of one lead), which leaves the agent to guess between it and ficiel_get_lead_context.

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 the safe read-only, idempotent, non-destructive profile, so the bar is lower, yet the description still adds substantial behavioral context: the is_group marker and conversation_id for groups, the best-effort caveat that a missing name may appear in message content, and the case/accent-insensitive partial matching. It stops short of describing pagination or result limits.

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 primary action, but it is a single run-on block that packs lookup modes, group handling, link fields, and best-effort caveats into dense clauses. It is not padded, but the wall-of-text structure 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?

With no output schema and only two parameters, the description carries the disclosure burden and does so well, covering the shape of results (link, link_readable, is_group) and match semantics. Only pagination/result-count behavior is left unaddressed, which is a minor gap for a read 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it clarifies that `handle` may be a @pseudo, phone number, or display name, that matching is partial and accent/case-insensitive, and that omitting `channel` searches all channels. That is genuine semantic value on top of the structured fields.

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 (retrieve one or more contacts by channel identifier or display name) and enumerates the distinct lookup modes, including group conversations. It is far more specific than a tautology, but it never names a sibling (ficiel_get_lead, ficiel_search, ficiel_get_lead_context) to disambiguate which one an agent should 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?

Usage is implied rather than stated: the description explains that omitting `channel` searches all channels and that partial/name lookups are accepted, which hints at when to reach for this tool. However, it gives no explicit when-not or 'use X instead' routing against the many lead-lookup siblings, so an agent must infer the boundary.

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 (readOnlyHint, idempotentHint, destructiveHint=false) couvrent déjà le profil de sécurité et n'exigent pas de redondance. La description ajoute néanmoins des éléments comportementaux importants : pagination de 500 messages maximum, ordre des plus récents d'abord, remontée vers l'historique plus ancien via next_cursor, garantie qu'aucun message n'est perdu, et indication par canal du vu du dernier message. Elle ne précise pas le coût potentiel ou la latence, mais couvre bien au-delà des 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?

Le contenu est front-loadé sur la nature de l'écran et le format des messages, mais plusieurs informations (ordre, pagination, next_cursor, garantie de non-perte, vu par canal) sont répétées ou dispersées. La phrase finale sur l'usage assistant est utile mais la description reste dense et gagnerait à être structurée en deux parties : ce qui est renvoyé, comment paginer. Aucune phrase n'est totalement superflue, mais la concision pourrait être améliorée.

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 doit expliquer ce qui est renvoyé, ce qu'elle fait bien : fiche du prospect, messages ordonnés avec transcriptions ou raison d'absence, pagination et statut de lecture par canal. Les paramètres étant entièrement documentés dans le schéma, il n'est pas nécessaire d'y revenir. Il manque simplement une mention des limites ou cas d'erreur éventuels, mais pour un outil en lecture seule et idempotent, l'ensemble est suffisamment complet.

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 de description du schéma est de 100 % : les paramètres lead_id, cursor et max_messages sont déjà documentés dans le schéma, y compris leur format et leurs bornes. La description rappelle l'existence de next_cursor et la limite de 500 messages par page mais n'apporte pas de sémantique supplémentaire sur les paramètres eux-mêmes (par exemple sur la structure exacte du curseur ou la validation de lead_id). Le socle de 3 s'applique.

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?

La description nomme précisément la ressource (contexte chronologique d'un contact, tous canaux confondus) et détaille la structure de l'écran (fiche, messages du plus ancien au plus récent, une ligne par message, vocaux et transcriptions). Le verbe principal est implicite (AFFICHE) mais le titre et le contenu rendent la fonction identifiable. Il manque toutefois une différenciation explicite avec les outils proches comme ficiel_get_lead, ficiel_get_conversation ou ficiel_fiche_prospect, ce qui limite la distinction directe au sein de la fratrie.

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?

La fin de la description indique le cas d'usage principal (« Pensé pour être lu d'un bloc par un assistant avant de décider quoi faire »), ce qui donne une orientation d'utilisation. En revanche, aucune alternative n'est citée : ni quand préférer ficiel_get_lead, ficiel_get_conversation ou ficiel_fiche_prospect, ni dans quels cas ne pas utiliser cet outil. L'usage reste donc implicite plutôt qu'explicitement guidé.

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 annotations (readOnly, idempotent, non-destructive), the description discloses concrete behavioral traits: images are resized to max 1568px, documents capped at 10MB, videos are never transmitted, and the response includes previously extracted text in full. These are operationally significant details 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?

The description is front-loaded with the core behavior and then layers constraints (size caps, video exclusion) and provenance in a compact sequence. It is slightly dense but each clause carries distinct information, 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?

There is no output schema, yet the description compensates by describing what comes back (image, embedded file, extracted text in full). For a single-parameter read tool with annotations already covering safety, 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?

With 100% schema coverage the baseline is 3, but the description adds real value by explaining where message_id originates (the 'media' field of a message from conversation, lead context, or search endpoints). That provenance guidance exceeds what the schema's 'Identifiant du message qui porte le média' conveys.

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 l'ORIGINAL d'un média d'une conversation') and immediately clarifies the goal ('pour le voir vous-même'). It also scopes the tool by excluding video, so an agent can tell exactly what it fetches versus what it does not.

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 names the prerequisite tools that produce message_id (ficiel_get_conversation, ficiel_get_lead_context, ficiel_search, media field), which gives clear routing context. It does not, however, contrast itself with adjacent media tools like ficiel_send_media or explain when retrieval is unnecessary.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that output includes circuit-breaker pause state, but says nothing about auth requirements, rate limits, or result shape.

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 tight sentence that front-loads the resource (what remains to send) before the qualifier (hourly/daily cap) and the pause flag. No filler, though it is a single flat 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 zero-parameter read tool with no output schema, the description must carry the return-value burden, and it does describe the content (per-channel remaining budget and pause status). Nothing essential is missing, though format/granularity is unstated.

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 the baseline is 4. There are no arguments whose meaning the description would need 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?

The description names a specific resource (remaining send budget per connected channel) and scope (before the hourly/daily cap, plus current pause state). It is clear what the tool returns, though it never distinguishes itself from look-alike siblings such as ficiel_get_channel_status or ficiel_statut_envoi.

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 only implied: an agent can infer you call this to check send headroom, but there is no explicit when-to-use, no when-not-to, and no pointer to the overlapping channel-status siblings. The single sentence gives no routing 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 (readOnly, idempotent, non-destructive), but the description adds genuinely non-obvious behavior: that a screen is rendered, that qualified/call-waiting/booked counts reflect contacts moved to the stage DURING the period, and that the window never extends before activity_since. Those counting and windowing rules materially affect how results must be interpreted.

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 display action and the resource, followed by the metric inventory and then the interpretation rules. It is dense and only mildly redundant in enumerating ten metrics, but every clause carries meaning and nothing is buried at the end.

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 carries the return-value burden and it does so by listing the aggregates and the computed rates. Combined with the annotation-profile and only two well-documented parameters, the definition is complete enough for correct invocation, though the exact return shape is still 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 both parameters are already documented in the schema and the baseline is 3. The description references the period and time series but adds no syntax or format detail 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 verb+resource are clear ("AFFICHE UN ÉCRAN" / "Statistiques de l'organisation") and the description enumerates the exact aggregates returned, which distinguishes it well from the funnel, channel-specific and synthesis siblings. It stops short of naming any sibling explicitly, so it earns 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?

Usage is implied (this is the org-wide statistics page over a period) but there is no explicit statement of when to prefer it over ficiel_get_stats_by_channel, ficiel_get_funnel or ficiel_synthese. The reader must infer the choice from the metric list.

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, non-destructive, non-open-world, so the safety profile is covered by structured data. The description adds that output is one block per account with its logo, which is modest but real UI/behavior context. It does not cover pagination, channel coverage when none are connected, or output shape beyond the visual metaphor.

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?

Two tightly packed clauses with no filler and the scoping constraint (by connected channel, over a period) is front-loaded. Slightly denser than ideal but every phrase 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?

For a single-optional-parameter read tool with no output schema and annotations covering safety, the description is close to sufficient. It is thin on what happens with zero connected channels and does not describe the aggregate set returned, which matters since there is no output schema to fall back on.

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?

Only one parameter exists and the schema description coverage is 100%, so the schema already documents period_days with its default, min and max. The description adds 'sur une période' but no syntax, boundary behavior, or timezone details. Baseline 3 is correct 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?

States a specific verb ('AFFICHE UN ÉCRAN') and resource (stats by connected channel), and explicitly anchors to the sibling ficiel_get_stats by saying the aggregates are 'les mêmes... découpés par canal connecté'. That differentiates it from get_stats and from channel-adjacent tools like get_channel_status, though 'un écran' is UI-flavored rather than API-precise.

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 reference to ficiel_get_stats implies when to choose this tool (same aggregates but split by channel), but there is no explicit when/when-not statement or guidance on choosing between this and ficiel_get_channel_status or ficiel_compare_periods. Usage is implied rather than stated.

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, idempotentHint, destructiveHint=false, openWorldHint=false). Beyond that, the description discloses a behavior the annotations cannot: this tool renders an interactive widget with Relancer / Voir la conversation / Ne plus proposer buttons, and that Relancer opens a follow-up card in the widget. It omits any statement of pagination behavior despite a cursor parameter.

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 definition is front-loaded with the widget nature of the tool, then moves to filtering rules, with no obvious filler sentences. It is somewhat dense and long, but every clause (card fields, buttons, eligibility exclusions) contributes 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 does the work of explaining the return shape by describing the per-contact card and its fields, plus the interactive buttons. The main residual gap is that cursor-based paging is never mentioned, but selection criteria and widget behavior are otherwise complete.

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 6 parameters, so the schema already carries parameter documentation and baseline 3 applies. The description reinforces vus_seulement and implies the stage/channel filters via the card fields, but adds no syntax or format detail 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 uses a specific verb+resource ('AFFICHE UN WIDGET : la liste des contacts à relancer') and enumerates exactly what each card contains and which actions it exposes, so the agent knows precisely what this tool produces. It does not, however, explicitly distinguish itself from close siblings such as ficiel_find_dormant_leads or ficiel_carte_relance; it only alludes to 'les relances de Ficiel'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong eligibility semantics (only contacts who have replied at least once, excluding blacklist, 'Ne pas contacter', skipped stages, and excluded contacts) and explains vus_seulement=true. But it never states when to reach for this tool versus the many sibling list/follow-up tools, so 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 declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds meaningful behavioral context beyond annotations: pagination rules (limit default 10, max 30), cursor semantics (next_cursor), and the guarantee that text is never truncated. Doesn't describe error behavior or what happens with an invalid version_id.

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 front-loaded: ordering (newest to oldest), the key semantic (state BEFORE modification), the field list, pagination rules, and the usage purpose. Every sentence earns its place with no redundancy.

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?

Three optional params, no output schema, but the description compensates by describing the returned field structure (version_id, date, taille, instructions entières) and the pagination contract. Complete enough for an agent to call correctly 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 baseline is 3. The description adds value beyond the schema by explaining cursor usage ('cursor = next_cursor de la page précédente') and the single-version retrieval mode ('Avec version_id, renvoie cette seule version'), which clarifies the mutual-exclusion semantics between pagination and version_id lookup.

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 (list versions of Kord configuration) and adds a non-obvious semantic precision: each version is the state of AVANT une modification, and each entry contains the full text. Distinguishes itself clearly from siblings like ficiel_get_agent_config.

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 names the alternative action it precedes: 'Sert à retrouver un état antérieur avant ficiel_restore_agent_config_version.' This tells the agent exactly when to use this tool versus the restore sibling.

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 safety (readOnly, idempotent, non-destructive), so the description's added behavioral depth is notable: it explains per-channel reliability of last_outbound_seen, that 'inconnu' never means 'not read', how link vs link_readable behave, and that group participants are inferred from messages. This is exactly the operational nuance an agent cannot get from structured fields.

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?

Purpose and sort order are front-loaded, and the filter enumeration follows logically. The middle section on last_outbound_seen, links, and group participants is dense and reads as one long paragraph, which slightly hurts scannability, but every clause conveys real 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 an 11-parameter tool with no output schema, the description carries the return-shape burden well: it describes each item as a summary (name, channel, stage, tags, full last message), documents link/link_readable, last_outbound_seen values, and group vs direct shape. An agent has enough to call 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 description coverage is 100%, so the baseline is 3 and the schema already documents all 11 parameters including enums and ranges. The description mostly restates the filter list; its only genuine addition is the cross-reference to ficiel_list_tags_and_stages for exact tag names, which is marginal value.

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 (paginierte Liste der Konversationen der Organisation), the sort order (letzte Nachricht zuerst), and the scope (Direkt- UND Gruppengespräche). It also distinguishes itself from the detail view by noting each item is only a summary with detail in the full conversation, routing the agent to ficiel_get_conversation.

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 context: it is the filtered, paginated listing tool and points to ficiel_list_tags_and_stages for exact tag names, and to the full conversation for detail. It does not explicitly contrast itself with ficiel_search or say when a listing is preferable to a search, so it falls short of the 5-level when/when-not/alternatives framing.

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 readOnlyHint/idempotent/destructive=false, and the description reinforces 'Lecture seule.' It adds real behavioral context beyond annotations: the returned fields, the legacy=true flag with its consequence (tags/notes cannot be restored), and the linkage of merge_id to the unmerge tool. It does not describe pagination or filtering behavior, keeping it from 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?

Single dense sentence front-loads the core scope ('fusions ENCORE ACTIVES... fiche principale') then lists fields and the legacy caveat. All content earns its place, though the enumeration of returned fields and mid-sentence reference to another tool slightly compress 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?

For a read-only, single-parameter list tool with no output schema, the description supplies the essential missing pieces: what is returned, the meaning of merge_id, the legacy caveat, and the read-only stance. Adequate for correct invocation; only filtering/pagination and empty-result behavior are 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?

Only one parameter (lead_id) with 100% schema coverage that already documents it as the primary contact. The description adds no syntax, format, or edge-case detail for lead_id beyond implying it is the subject fiche. Baseline 3 holds 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?

States a specific verb (Liste) and resource (fusions ENCORE ACTIVES) scoped to the primary fiche, and explicitly names the returned fields (merge_id, fiche réunie, date, auteur, conversations déplacées). It also cross-references the sibling ficiel_unmerge_leads, making it clearly distinguishable from ficiel_merge_leads.

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?

Implicitly clarifies the use case: return only active merges where this contact is the main fiche. It explicitly points to ficiel_unmerge_leads for the merge_id's purpose, but does not state when NOT to use it (e.g., use ficiel_get_lead for general contact info) nor name a direct alternative for listing passive/legacy merges.

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/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the four state values and the important constraint that 'auto' rules are platform-mandatory and never offered for modification, which an agent could not infer from annotations or schema 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?

Two sentences, front-loaded with the core purpose, and the fairly long enum gloss is justified because those values drive agent decisions. Slightly dense 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?

For a read-only filtered list with no output schema, the description covers purpose, filter states, and follow-up actions. It stops short of indicating what a returned rule record contains (rule text, category, timestamps), a minor gap given there is no output schema to fall back on.

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 beyond the schema by explaining what each review_state enum value signifies in terms of workflow. It does not clarify the interaction between active_only and review_state, which keeps it from a 5.

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 règles apprises par Kord') and enumerates the rule categories (style, objections, ouvertures) plus the validation state carried in the result. An agent can distinguish this immediately from the sibling ficiel_approve/dismiss/convert_learned_patterns tools, which the description explicitly names.

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?

Explains that 'proposed' means awaiting the user's decision and points to the exact sibling tools to act on it (approve, dismiss, convert), which effectively routes read vs. write. It does not spell out a negative case (e.g., use this before deciding, not after), but the context 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 cover the safety profile (readOnlyHint, destructiveHint=false, idempotent), but the description adds meaningful behavioral detail beyond them: only text cards are listed, voice cards are excluded, and it shows the exact text that would be sent with age in days. The closing 'Lecture seule : rien n'est envoyé' reinforces rather than contradicts 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 core action ('AFFICHE UN ÉCRAN') followed by scope and return fields. It is a dense single block rather than short, but each clause earns its place by describing contents and the text-only restriction; nothing is redundant 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 must carry return-value information, and it does: it enumerates each card's fields (card_id, contact, canal, conversation_id, exact text, reason, age). Combined with the text-only scope note and read-only nature, 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 limit, cursor, and the channel enum are already fully documented in the schema. The description adds no parameter syntax, defaults, or pagination hints beyond what the schema provides, which is the baseline 3 when structured data 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?

States a specific verb and resource ('Liste les cartes de Kord qui attendent une décision') and even describes the two card kinds (batch follow-ups and pending suggestions). It is clear and concrete, but it never names or contrasts with siblings like ficiel_carte_relance or ficiel_decide_card, so the sibling differentiation that would lift it to a 5 is absent.

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 implied by the content description ('cartes qui attendent une décision') and one exclusion is given ('une carte vocale se valide dans l'application'), which tells the agent not to look for voice cards here. However, there is no explicit when-to-use versus ficiel_decide_card / ficiel_carte_relance, and no stated preconditions, so it stays at the implied-usage level.

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, closed-world), and the description usefully adds pagination (next_cursor), an exact total, and full-text output. However, its claim that the default shows 'only those still pending' conflicts with the schema's stated default (pending AND failed of the last 7 days), introducing confusion about actual behavior.

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 action, then scope, default, and pagination in a compact set of clauses. The 'AFFICHE UN ÉCRAN' parenthetical is slightly odd but harmless; overall dense with little waste.

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 list tool with full schema coverage and rich annotations, the description covers scope, default filtering, and pagination/total. The one gap is the default-filter discrepancy noted above; otherwise nothing essential to invocation 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 all four parameters are already documented in the schema. The description echoes pagination (next_cursor) and scoping (conversation) but adds no format or semantics beyond what the schema provides; 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 (List) and resource (scheduled messages), and clarifies scope as organization-wide or a single conversation. It is distinguishable from siblings like ficiel_schedule_message (create) and ficiel_cancel_scheduled (mutate), though it does not name those alternatives directly.

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?

Provides an implied default ('Par défaut, seulement ceux encore en attente') but offers no explicit when-to-use / when-not-to-use guidance and never names an alternative tool. Adequate but leaves routing 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, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds genuine return-content context beyond the annotations by disclosing that each channel entry carries delegation state and quiet hours, which an agent could not infer otherwise.

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 sentence, front-loaded with the reason to use the tool and then the payload contents. It is dense but slightly run-on due to stacked parentheticals; every clause still carries information, so it is efficient overall.

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 the return-value burden, and it does enumerate the entity groups returned plus per-channel state details. It is adequate for a zero-parameter reference tool, though it could note the shape or ordering of the returned collections.

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 the baseline is 4 under the scoring rules. There is nothing further for the description to disambiguate on the input side.

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-like intent (a reference list of exact names to reuse in other tools) and enumerates exactly what is returned: tags, pipeline stages with stage_key and label, and connected channels. It is clearly distinguishable from mutating siblings like add_tag, create_tag, update_tag, and set_stage, though it does not name a sibling directly.

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 clause 'les noms exacts à utiliser dans les autres outils' gives a clear reason and moment to call this tool: resolve identifiers before invoking tools that take tag or stage names. There are no explicit when-not conditions or named alternatives, but the usage context is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: that this is read-only and that all mutation flows live in the Ficiel UI, plus the semantic rule 'Un Admin a toutes les permissions', which explains how to interpret the permission fields. It does not discuss ordering, volume or result limits.

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?

Purpose is front-loaded in the opening clause, followed by the field inventory and then the read-only caveat. The long parenthetical permission list is dense but earns its place since there is no output schema to carry that information. No filler 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?

With no output schema and zero parameters, the description carries the full burden of explaining what comes back, and it does so field by field, including the non-obvious rule about Admin permissions. It also closes the loop on mutation by pointing to Ficiel. Nothing an agent needs in order to call and interpret this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The field enumeration describes output rather than inputs, which is appropriate here.

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 resource unambiguously ('Les membres de votre organisation') and enumerates the exact fields returned (email, Admin/Agent, owner status, login state, invitation status, permissions, hidden tags, visible channels). It is immediately distinguishable from every sibling, all of which operate on leads, conversations, tags or automations rather than team members. It lacks an explicit verb, but the purpose is not in doubt.

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 an explicit when-not boundary: 'Lecture seule : inviter, modifier ou retirer un membre se fait dans Ficiel', telling the agent not to attempt mutations through this tool. There is no sibling alternative to route to for listing members, so no alternative needs naming. It stops short of stating a positive trigger condition (e.g. when to consult the team list), 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the UI ordering, the exact fields returned, the variable syntax inside template text, and the fact that filtering can target title or body.

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 a compact block of sentences with the core purpose and ordering front-loaded, and every clause carries information about scope, ordering, return fields, or filtering. It is slightly dense but not 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 read-only listing tool with no output schema, the description does useful work by enumerating returned fields and explaining variable syntax and ordering. Pagination behavior is covered by the input schema, so the only minor gap is not naming sibling alternatives or explaining cursor continuation in prose.

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 limit, query, cursor, and category are already documented in the schema. The description only restates that filtering works by word or category, adding no syntax or format detail beyond what the schema provides. 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 precise verb and resource: it lists message templates for the organization. It also specifies scope, ordering (pinned then most used), and returned fields, so an agent can distinguish it from sibling tools like ficiel_resolve_template or ficiel_save_template 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 description implies usage for browsing or searching templates and notes it is read-only, which helps an agent avoid mistaking it for a mutation. However, it never explicitly names alternatives such as ficiel_resolve_template or ficiel_save_template, nor states when this tool should be preferred over them.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond them: that the clips are unmodified recordings of your own voice sent as-is, and it enumerates the returned fields despite 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?

Three dense sentences, front-loaded with the verb and resource, then the returned fields, then the usage pointer. Slightly long, but each sentence carries distinct information and 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?

With no output schema and no parameters, the description fully compensates by listing the return fields and their meaning, plus cross-referencing the sibling tools where the clip_id is consumed. An agent has everything needed to list and then use a clip.

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?

No parameters, so the baseline is 4. The description adds meaning to the output key clip_id by explaining what it is for (sending a voice message or referencing an automation step), which is genuine value beyond the empty 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?

Specific verb (Liste) plus resource (bibliothèque de vocaux préenregistrés de votre organisation) and it enumerates the returned fields (clip_id, nom, transcript, durée). An agent can tell it apart from the many write/send siblings immediately.

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?

Explains the purpose of the returned clip_id by routing to two concrete consumers (ficiel_send_media with kind=voice, or voice_clip_id in an automation step), giving clear downstream context. It does not say when NOT to use it versus other list tools, but the read-only scope is 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?

Adds substantial behavior beyond the annotations: stage transitions to 'RDV pris' only if the contact was before that step, contacts already no-show/signed/lost keep their stage with only the date updated, the action is journalized and counts in the flow, and no message is sent. This complements destructiveHint/idempotentHint with concrete semantics rather than repeating 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 core verb and resource, then layers stage behavior and the no-message caveat. It is dense but each clause carries information; only the stage-exception parenthetical is slightly heavy.

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-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the remaining needed context — stage-transition rules, journaling, absence of messaging, and required scope. No output schema exists, so return values need not be explained.

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 both parameters (lead_id, appointment_at with ISO 8601 format) are already documented. The description reinforces that the real date/time is written to the card but adds no syntax or format detail beyond the schema; 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 — recording that an appointment was booked with a contact — and clarifies it is done 'hors de Ficiel' (external agenda/CRM), which pins down the exact intent versus siblings like ficiel_book_slot. An agent can identify the right tool 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?

Gives clear context: it records an already-taken external appointment, and explicitly routes message confirmation to ficiel_send_message ('N'envoie aucun message'). It also states the required 'write' scope. It stops short of explicitly contrasting with ficiel_book_slot or ficiel_set_stage, but the 'hors de Ficiel' framing makes the distinction inferable.

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 beyond the annotations by asserting the operation is reversible, sends no messages and deletes nothing, and documents the idempotent outcome ('rien ne change et la réponse le dit (already_in_state)'). This meaningfully reinforces and extends the idempotentHint/destructiveHint metadata.

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?

Short, front-loaded with the action, then the behavioral caveats. Every sentence carries information; minor redundancy between 'réversible' and 'ne supprime rien' but nothing 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?

No output schema exists, and the description compensates by describing the response signal (`already_in_state`) and the required write scope. For a one-parameter idempotent flag tool, this is sufficient 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% for the single `conversation_id` parameter, so the schema already carries the semantics. The description adds no format or constraint detail beyond it, 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?

States a specific verb and resource ('Marque la conversation comme lue') and clarifies the semantics by likening it to opening the thread in the UI. It doesn't explicitly name the sibling `mark_conversation_unread`, though the counterpart relationship is obvious from the name.

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 implied ('comme l'ouverture dans l'interface') and a prerequisite is stated ('Portée « write » requise'), but there is no explicit when-to-use / when-not-to-use guidance or reference to an alternative tool.

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 idempotentHint=true and destructiveHint=false, but the description adds real context: it states the operation is reversible, sends no message, deletes nothing, requires 'write' scope, and returns an 'already_in_state' marker on no-op. That is useful behavioral disclosure beyond the structured fields, short only of return-format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the action and followed by scope, side-effect guarantees, and the no-op case. No padding, though 'comme dans l'interface' is the least informative 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 mutation tool with no output schema, the description covers the safety profile, reversibility, required scope, and the notable already_in_state response. An agent has what it needs to call this correctly; only the response shape 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?

There is a single parameter (conversation_id) with 100% schema description coverage, so the schema already tells the agent exactly what to supply. The description adds nothing about the identifier format, which is the baseline expectation when the schema does 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?

States a specific verb and resource: putting a conversation back into the unread state, and clarifies the scope covers both one-to-one and group conversations. It does not explicitly name the sibling ficiel_mark_conversation_read as its counterpart, though the name pairing makes the inverse operation discoverable.

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 implied by the description of the operation, and the note about 'already_in_state' tells the agent what happens when the precondition is not met. There is no explicit statement of when to prefer this over alternatives such as ficiel_mark_conversation_read or ficiel_pin_conversation.

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 annotations: it says conversations are re-pointed, that a channel collision archives one side without deleting any message, that tags/notes/events are combined, that the master is completed without overwriting, that the satellite leaves the lists, that no message is sent, that 'write' scope is required, and that merge chains are rejected. The annotations only flag destructive/idempotent; the description supplies the actual blast radius.

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 action and scope in the first clause and packs genuinely load-bearing details (archival behavior, reversibility, prohibitions). It is dense and slightly run-on with parentheticals, but virtually 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?

For a destructive, irreversible-looking operation with no output schema, the description covers effects, precedence rules, reversibility handle (merge_id), confirmation requirement, and authorization scope. An agent has everything needed to decide and invoke safely.

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 baseline is 3, but the description adds real meaning: it clarifies the asymmetric direction (satellite is absorbed, master survives) and explains the purpose of confirm as the explicit same-person attestation. It also documents the returned merge_id, which feeds the undo call.

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 (merge satellite_lead_id INTO master_lead_id) and immediately disambiguates the direction, which is the one thing an agent could get wrong. It also names the sibling tool that reverses it (ficiel_unmerge_leads), so it is clearly distinguishable from the surrounding ~70 tools.

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 usage condition (two fiches of the same person) and a prohibition (fusion chains are forbidden), plus the guard that confirm must be true. It routes to the undo path (ficiel_unmerge_leads) with its precondition ('tant que rien n'est purgé'), but does not compare against non-merge alternatives such as update_lead.

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 idempotentHint=true and destructiveHint=false, but the description adds useful behavioral detail: it is reversible, sends no message, deletes nothing, returns already_in_state when no change occurs, and requires write scope. Some of this overlaps with annotations, but the already_in_state response and write-scope requirement add real 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 description is short, front-loaded with the action, and every sentence adds value: scope, reversibility, no-send/no-delete behavior, idempotent response, and permission requirement. There is no 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 simple one-parameter mutation with no output schema, the description covers the critical behavioral details an agent needs: effect, non-effects, reversibility, idempotency, response behavior, and required write scope. Nothing essential 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?

There is one parameter and schema description coverage is 100%, so the schema already documents conversation_id clearly. The description does not add syntax or semantic detail beyond the schema, making the baseline 3 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 and resource: pinning a conversation to the top of the inbox, and clarifies it applies to one-to-one or group conversations. It does not explicitly name the sibling unpin tool or otherwise differentiate among alternatives, so it is clear but short of the full 5 criteria.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: pinning a conversation, applicable to both two-person and group conversations. It does not state when not to use the tool or explicitly route the agent to ficiel_unpin_conversation for reversal, leaving that to inference from “Réversible”.

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 annotations by disclosing that nothing is sent, that the rejection feeds Kord's learning, and that for daily-batch cards the contact is additionally removed from follow-ups via an 'Ignorer' tag that is reversible from the contact sheet. That is exactly the side-effect and reversibility information an agent needs for a non-readOnly write. No contradiction with destructiveHint=false, since the tag removal is explicitly described as removable.

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 core effect ('Écarte... sans rien envoyer') and then qualifies it with the conditional exclusion rule, the text-only restriction and the scope requirement. Dense but every clause carries a distinct constraint; the parenthetical about the app/tag origin is slightly incidental.

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-parameter write tool with no output schema, the description covers the constraints, the conditional side effect and the required scope. It stops short of saying what the call returns (e.g. whether the tag or the learning update is echoed back), which would be the only remaining 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning to confirm_exclusion: it is only demanded for daily-batch cards and true authorizes removal of the contact from follow-ups. card_id itself is left to the schema, which is fine given its full documentation.

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 ('Écarte une carte de relance') plus a key differentiator: nothing is sent, unlike sending tools. It does not explicitly name the neighbouring choices (approve_card, defer_card, ne_plus_proposer), so the boundary with those siblings must be inferred.

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 implied through constraints (text cards only, write scope, confirm_exclusion required for daily-batch cards) but there is no explicit statement of when to reject rather than defer or approve a card. The conditional rule for the daily batch is well specified, but the choose-this-tool guidance is left 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/idempotentHint true and destructiveHint false, and the description adds real behavior beyond them: unresolved placeholders are left verbatim and surfaced in unresolved_variables, which must be reviewed before sending. It does not describe pagination or limits, but the response-content caveat is valuable given 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?

It is front-loaded with what is returned, then the unresolved-variable caveat, then the send follow-up, then the read-only note. Dense and mostly waste-free, though 'Lecture seule' partially duplicates the readOnlyHint annotation.

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 schema-less read tool with full safety annotations, it covers the essentials: what is rendered, what happens to unresolved variables, and which tool performs the send. What is missing is minor (no note on how the resolved text is formatted or any size limits).

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 only two UUID parameters (template_id, lead_id) already documented in the schema. The description only implicitly confirms the contact/template pairing and adds no 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?

The description names a specific verb (renvoie/rend) and resource (le texte d'un modèle rempli pour un contact) and even lists the interpolated variable syntax ({prénom}, {ig_handle}, {date}, {stage_pipeline}), making it clearly distinct from ficiel_list_templates, ficiel_save_template and ficiel_send_message.

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 routes the agent explicitly: 'N'envoie rien : le texte obtenu s'envoie ensuite avec ficiel_send_message (destinataire nommé obligatoire)', which names the sibling to use for the actual send and implies the review-before-send workflow. It does not give an explicit 'do not use this when…' clause, 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?

Beyond the annotations it explains that the change takes immediate effect on Kord's responses, requires 'write' scope, and — critically — that the operation is reversible because it saves the state it replaces as a new version. This last point adds meaningful nuance to the destructiveHint=true annotation rather than merely restating it. Extensive behavioral context the structured fields 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 core action, then effect, reversibility, use case, and scope. Every sentence carries real information, though the block is slightly dense for a single-parameter tool.

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 mutation tool with annotations covering the safety profile and no output schema, the description supplies the missing pieces an agent needs: immediate effect, reversibility/recovery path, required scope, and the origin of the required parameter. Nothing essential is left out.

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 single version_id parameter is already documented as a uuid in the schema. The description only points to the sibling list tool as the source, adding no format or semantics beyond the schema. 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?

The description states a specific verb (remet/restaure) and resource (Kord's configuration: custom instructions, prompt, profile) and anchors it to a version sourced from ficiel_list_agent_config_versions. An agent can distinguish this from ficiel_edit_agent_prompt / ficiel_edit_agent_profile 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?

It states a clear use case ('permet d'annuler une édition des instructions') and routes the agent to ficiel_list_agent_config_versions to obtain the version_id. It does not explicitly state a when-not condition or contrast against the sibling edit tools, but the intended context is 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false) it discloses partial-update semantics ('seuls les champs fournis changent'), an immutable key, the side effect that excludes_from_relance removes contacts from follow-ups, and the required write scope. The statement that it deletes nothing does not contradict destructiveHint, since the destructive effect is the relance exclusion, but that nuance is left implicit.

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 that is front-loaded with the create-vs-modify decision and then the constraints, with no filler sentences. Some constraint details duplicate the schema, which costs a little efficiency, but nothing is off-topic.

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 need not cover return values, and it compensates well: creation constraints, update semantics, side effects, and the permission requirement are all present. It leaves error behavior (invalid key format, unknown stage_key collisions) unspecified, which is a minor gap for a write 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: stage_key naming rules (2–40 chars, lowercase/digits/underscore, must start with a letter), the purple default for color, and append-to-end placement. It also explains the behavioral effect of excludes_from_relance rather than just restating the boolean.

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 precise verb+resource pair with upsert semantics: create a pipeline stage when stage_key is absent, otherwise modify the existing one. It clearly scopes the object to the pipeline stage definition rather than a lead's stage, which is the key distinction from siblings like ficiel_set_stage. It never names a sibling tool, so it stops short of full differentiation.

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 the condition that selects each branch (stage_key existence), states that label is required for creation, notes the key is immutable, and explicitly excludes behavior (no deletion, no reordering). It also states the 'write' scope prerequisite. What is missing is an explicit pointer to the alternative tools (e.g. ficiel_list_tags_and_stages for resolving a key), which is only implied via the schema.

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 readOnly=false, destructive=true, idempotent=false and openWorld=false, but the description adds genuinely new behavioral context: partial-update semantics ('seuls les champs fournis changent'), the category-null removal rule, and the required write scope. This reconciles the destructiveHint (field overwrite, not deletion) rather than contradicting it.

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 two operating modes are front-loaded and the rest is compact and information-dense. The repeated min/max length constraints ('titre 1 à 140 caractères, texte 1 à 4000') are redundant with the schema and dilute an otherwise tight definition.

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 carries the burden of explaining the response, and it says nothing about what is returned (e.g. the created template's id) or what happens on failure — a real gap for a create operation an agent may need to chain from. Parameter and behavioral coverage are otherwise solid for a 4-parameter 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 the baseline is 3; the description exceeds it by explaining the placeholder syntax the body accepts ({prénom}, {ig_handle}, {date}, {stage_pipeline}), which appears nowhere in the schema. The length limits it restates duplicate the schema, adding no extra value.

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 and splits it precisely by mode: no template_id creates a model, with template_id modifies that model. This cleanly separates it from the read-only siblings list_templates and resolve_template without the agent needing to open 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?

It gives explicit conditions for each mode (absence/presence of template_id) and adds clear exclusions — 'Ne supprime jamais un modèle, n'envoie aucun' — which tell the agent this is not a delete or send tool. It stops short of routing to an alternative for deletion, so it is strong but not fully 5-level when/when-not/alternatives 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context: results are ordered newest-to-oldest, paginated, and each hit is returned with its immediate neighbor messages, with full voice transcriptions (voice_transcription/excerpt) and message_kind values. This goes well beyond what annotations provide.

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 core purpose and then layers scope, transcription fidelity, syntax, context window, and ordering. Each sentence carries information, though it is dense and could be tightened; 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?

With no output schema, the description carries the burden of explaining returns and does so — found message plus surrounding context, message_kind, transcription fields, ordering, and pagination. Combined with 100% schema coverage of the filters, 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning for the key 'query' parameter — AND semantics for multiple words, quotes for phrases, and '-word' exclusion — which the schema's terse 'Mots ou expression à chercher' does not convey.

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: full-text search across all messages of the organization, explicitly including voice transcriptions. No sibling is a general message search tool, so this is naturally distinguishable from list_conversations/get_conversation 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?

Usage is implied (it is a message search tool) and the query syntax is explained, but there is no explicit when-to-use versus alternatives such as ficiel_get_conversation or ficiel_list_conversations, nor any exclusion criteria. Adequate but with a clear gap in routing guidance.

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