Boncourant

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: the result is a prospective recommendation rather than a historical line-by-line audit, and it guarantees that when no offer beats the current contract, recommended_offer never points to a more expensive catalogue offer. It stops short of covering engine-version behavior or cost/rate characteristics.

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 dense sentences with the purpose and the sibling disambiguation front-loaded, followed by scope boundary, output guarantee and input prerequisite. Every sentence carries information, though the output-guarantee clause is unusually granular for a description this 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 an output schema present, annotations covering the safety profile, and full parameter documentation, the description supplies exactly the missing layer: scope (already-extracted bill vs raw PDF), the alternative tool, the prospective nature of the verdict, and the key output guarantee. Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100% across all 9 properties, including the HP/HC conditional fields and the optional cost reference, so the schema already carries the parameter meaning. The description only gestures at 'champs structurés' and the PDF-extraction prerequisite, adding no syntax or format detail beyond the schema. 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 (évalue/analyse) applied to a precisely scoped resource: a residential bill that has already been extracted into structured fields, analyzed via the versioned engine. It explicitly distinguishes itself from the sibling 'simulate' and from the historical audit tools, so an agent can route correctly 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?

Names the alternative ('pour une estimation sur paramètres sans facture, appelez simulate') and the condition that selects it, and rules out a competing interpretation ('pas du contrôle historique de toutes les lignes facturées'). It also states the prerequisite ordering: extract the PDF upstream, then call this tool with the fields.

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 and non-destructive behavior, so the safety profile is covered. The description adds real scope boundaries beyond that: it does not consult market prices, does not compute termination penalties, and treats pricing_type as a canonical input rather than an inferred value. It says nothing about permissions or failure modes, but for a read-only computation this is solid.

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

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

Three compact sentences, front-loaded with the core computation, followed by the exclusion and the routing instruction. No filler; each sentence carries a distinct constraint.

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?

An output schema exists so return values need no explanation, and the annotations carry the safety profile. Scope, exclusions and the sibling hand-off are all present; the only shortfall is that four of five parameters remain semantically unannotated.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It meaningfully clarifies pricing_type (a canonical value, never inferred from free text) and gestures at the inputs ('dates et clauses extraites'), but end_date, auto_renewal, evaluation_date and notice_period_days get no added semantics. Partial compensation for a full coverage 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?

States a precise verb+resource: it computes only the contract deadline and notice period from extracted dates and clauses. It immediately scopes itself against the sibling renewal_advisor, so an agent can distinguish the two 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?

Explicit when-to-use ('dates and clauses only, no market prices') and when-not-to-use ('for a renewal decision with market and catalog, call renewal_advisor'), plus an additional exclusion ('does not quantify termination penalty'). Both the alternative and the selecting condition are named.

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 indicate a safe read-only and idempotent operation. The description adds valuable behavioral context: it uses official Enedis coefficients and specifies an explicit, bounded linear fallback for kWh when coefficients are unavailable. This goes beyond the annotations without contradicting them.

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

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

The description is two dense, purposeful sentences. It front-loads the core action, then adds the key fallback behavior. There is no fluff, repetition, or irrelevant detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 7 parameters, the output schema, and the annotations, the description is largely complete: it explains the calculation basis, the parameter roles, and the fallback behavior. Minor gaps remain around the exact bound of the linear fallback and the absence of any routing guidance relative to siblings, but these are separate concerns.

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

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

Schema description coverage is 0%, but the description compensates reasonably: it maps segment, option, and puissance_kva to the Enedis profile selection, and 'consommation'/'total TTC' clearly map to period_kwh and period_total_ttc_eur. The period dates are implied by 'd'une période', though not explicitly described.

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 ('Annualise') with a clear resource: consumption and/or total TTC over a period, using official Enedis profile coefficients. It is clear and detailed, but it does not explicitly distinguish itself from sibling tools such as analyze_bill or decompose_invoice, so it misses the top score.

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 does but provides no guidance on when to choose it over sibling tools, nor any exclusions or prerequisites. There is no mention of alternatives like analyze_bill or simulate, and no scenario-based usage instruction.

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. The description adds valuable behavioral context: it avoids using posterior information, restricts conclusions to provided evidence, and explicitly disclaims market-wide coverage. There is no contradiction with 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?

Two dense, front-loaded French sentences with no filler. Every clause adds meaning: the comparison baseline, the restriction against future data, and the evidence-based limit of conclusions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and annotations cover safety/idempotence, the description explains the core evaluation logic well. However, it omits guidance on the optional materiality threshold and how feasibility values should be interpreted, leaving a small but real completeness gap for a tool with this input 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 0%, so the description needed to compensate for parameter meaning. It implicitly maps 'contract' and 'alternatives' through its comparison wording, but it says nothing about materiality_eur_year or field-level semantics such as feasibility, validity periods, or comparison_basis. This is a significant gap given the complex nested 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?

The description uses a specific verb ('Compare') and identifies the exact resource: a signed contract against dated, valid, feasible offers available at signing time. It clearly distinguishes the historical-optimality assessment from a general market-wide comparison, making the tool's purpose unambiguous even among siblings.

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 provides clear context: use this tool to compare only offers that were dated, valid, and feasible at signature, and never to claim whole-market coverage. However, it does not explicitly name alternatives or state when not to use the tool relative to siblings like assess_ppa or renewal_advisor, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral caveats: the analysis is conditional, scenarios must not be framed as forecasts, and general guidance must not be presented as individualized legal or tax advice.

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 no filler: purpose is front-loaded, the prerequisite workflow appears second, and the necessary caveats are last. Every sentence carries distinct 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 tool with a very rich schema and output schema, the description covers the core workflow and disclaimers well. However, it leaves matched_profile undocumented and gives no guidance on when callers should provide it or how it relates to customer scenarios, so completeness is acceptable but not tight.

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

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

Schema description coverage is 0%, so the description had to compensate, but it only clarifies customer roles, contract extraction artifacts (extract.ppa, extract.reading_coverage), and the notion of client-provided economic sensitivities. It does not explain matched_profile, most customer fields, or how the scenarios map to inputs; the burden on the description is largely unmet.

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

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

The description identifies a specific action ('Produit une analyse PPA conditionnelle') and resource (PPA), names the supported customer roles, and lists the analysis dimensions delivered. It also distinguishes itself from extract_energy_document by prescribing that tool as a prerequisite rather than duplicating extraction.

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 specifying that contract-text analysis must start with extract_energy_document and then pass extract.ppa and extract.reading_coverage. It does not explicitly state when not to use the tool or compare it to sibling analysis tools, so it stops short of a full 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond those flags: it will not extrapolate a single peak, and it can return a non-conclusive result for C4 when an unlabeled peak falls between P1 × 0.93 and P4 × 0.93. This is valuable edge-case 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 description is two dense sentences with no filler. The core evaluation rule is front-loaded, and the second sentence packs high-value requirements, thresholds, and an inconclusive condition without 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?

Given the 11-parameter schema, the description covers the most decision-critical logic and the output schema presumably covers the return shape. Still, it does not explain when to supply max-demand values, measurement period, or measurement basis, so an agent may under-specify a valid call.

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

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

Schema description coverage is 0%, so the description must compensate. It does map several key concepts: evaluation_date ('date demandée'), subscribed_powers_kva (P1–P4), available_contract_tiers_kva ('paliers du contrat'), and connection_segment (C5/C4). However, important parameters such as max_demand_kw, max_demand_kva, measurement_basis, and measurement_period_days are not explained or connected to the evaluation logic.

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 action and resource ('Évalue la puissance à la date demandée') and adds a behavioral constraint that differentiates it from generic analysis tools: it does not extrapolate an isolated peak. The C5/C4 rules further specify exactly what kind of subscribed-power evaluation this tool performs.

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 provides clear contextual usage conditions: C5 candidacy requires a full year of official apparent peaks plus contract tiers, while C4 requires P1–P4 and has an explicit inconclusive case. It does not name sibling alternatives or say when not to use this tool, so it stops short of full alternative 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?

Beyond the annotations, the description discloses that raw input is deleted at job completion, results expire within 24 hours, the operation creates only temporary state, and it never acts on a vendor or customer account. This adds meaningful behavioral context that the annotations alone do not convey.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value: the action, the immediate return, the follow-up mechanism, and the data lifecycle. No filler or 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?

Given the tool's complexity, output schema, and sibling set, the description covers all essential operational aspects: what it returns, how to track it, data expiration, and side-effect boundaries. An agent has enough context to invoke it correctly and know what to expect.

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 80%, so the schema already documents most parameters. The description adds no new parameter-level detail, but it does not need to significantly compensate; the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it creates and launches an idempotent temporary MCP study for any supported Boncourant analytical tool. It clearly distinguishes itself from sibling analytical tools by emphasizing that it returns a receipt rather than the analysis result itself.

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 clearly indicates this tool is for launching an asynchronous study and explicitly directs users to get_analysis_study for tracking. It does not explicitly enumerate when-not-to-use cases relative to the direct analytic siblings, but the intended workflow is evident.

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. The description adds meaningful behavioral context: it aggregates lines into canonical postes, verifies totals, and returns the method, version, and input hash. This provides insight into the computation and output without contradicting any annotation.

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 single compact sentence that front-loads the main action (aggregation) and then adds the verification and return-value details. Every clause adds useful information, and the list of canonical categories is efficient rather than verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations cover safety and an output schema exists, the description sufficiently explains the tool's purpose, inputs, and return envelope. It does not specify behavior on reconciliation failure, rounding tolerance, or the semantics of optional stated totals, but these are relatively minor given the structured schema and annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It does map conceptually to the three parameters: 'lignes de facture' corresponds to line_items, and 'totaux HT/TTC déclarés' corresponds to stated_total_ht/ttc. It also lists categories matching the component enum. However, it does not explain the confidence field, optional amount fields, or how null/absent totals affect behavior, so compensation is only partial.

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 specific verbs ('Agrège', 'vérifie') on a clear resource (invoice lines) and names the canonical output categories (énergie, TURPE, accise, CTA, TVA, etc.). It clearly distinguishes this tool from siblings like extract_energy_document or analyze_bill by focusing on aggregation and reconciliation of already-extracted lines.

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 'déjà extraites' clearly signals that this tool is meant to be used after extraction, implying the extraction workflow step. It also states what the tool verifies (sums vs declared HT/TTC totals), which gives context for when to call it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the data source ('snapshot public le plus récent depuis market_observation') and the explicit missing-data signal when no recent observation exists, which is a meaningful caveat for an agent interpreting results.

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 scope, the exclusion, the alternative tool, the data source and the missing-data behavior all front-loaded. Every clause earns its place, though the density is at the upper limit before it becomes hard to parse.

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 an output schema present (return values need not be explained), full annotation coverage and a fully documented parameter, the description supplies everything else an agent needs: scope, exclusions, source of truth and the empty-result signal.

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 'asof' parameter is fully documented in the schema (ISO 8601, default today). The description adds no syntax or semantics beyond that, so the baseline of 3 applies — 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 ('Lit') and resource (indicateurs forward EEX France) and enumerates the exact contract horizons covered (CAL Y+1, CAL Y+2, M+1). It also names the sibling it is not (renewal_advisor), so an agent can distinguish it without opening any schema.

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

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

Explicitly bounds usage with 'sans décision contractuelle' and routes the agent to the alternative: 'pour une recommandation de renouvellement, appelez renewal_advisor'. Both the when-not and the alternative are stated, leaving nothing to inference.

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

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

Beyond the readOnly/idempotent annotations, the description discloses behavior an agent could not get from structured fields: extraction runs in memory, sensitive identifiers are removed from the response, the document is not retained by Boncourant, uncertain fields require confirmation, and crucially that during the test phase extraction is performed by DeepSeek in China with no transfer guarantees. This is exactly the kind of non-obvious, decision-relevant context the description should 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?

Three sentences, front-loaded with what the tool does, then the privacy constraint and the retention/confirmation caveats. Every sentence carries information and none is padding, though the run-on first sentence packs three distinct behaviors together.

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?

An output schema exists, so return values need not be described, and the annotations already cover the safety profile. Given that, the description supplies everything an agent needs to invoke it responsibly: what it ingests, what it does with the data, the third-party transfer risk, and the non-retention guarantee.

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%, so the description needs to compensate, but it only vaguely alludes to 'un PDF ou un texte' without distinguishing document_file / document_base64 / document_text, and never mentions document_kind, segment, or evaluation_date at all. The oneOf input-alternative structure and the enum values that shape the analysis remain undocumented in prose.

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 (extrait) and resource (PDF/texte de facture ou contrat) and adds that it strips sensitive identifiers and immediately runs the applicable deterministic methods, so an agent understands it is an extract-plus-analyze entry point. It does not, however, name or contrast itself with obvious siblings like analyze_bill or decompose_invoice, so sibling 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 agent can infer this is the ingestion step for invoices/contracts, and there is a real when-not-to constraint ('n'envoyez pas de document contenant des données personnelles réelles'). But nothing tells the agent when to pick this over analyze_bill, decompose_invoice, or annualize_invoice, nor any prerequisites.

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 readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: the PDF URL is private and valid for only two minutes, and the receipt is a secret that authorizes only this study and must not be logged or shared. This is important operational guidance not present in 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?

The description is two sentences with no wasted words. It front-loads what the tool returns and then adds the critical security caveats. Every sentence 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?

Given a single parameter, rich annotations, and an output schema, the description provides sufficient context: what is returned, the time-limited PDF URL, the secret handling requirement, and the precondition that the study be completed. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry the meaning of the 'receipt' parameter. It does so by explaining that the receipt is secret, authorizes only this study, and should not be logged or shared. It does not explain where to obtain the receipt or the exact format, but the pattern in the schema covers format, and the semantic role is clarified.

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 returns the Markdown report of a completed PPA study plus a private PDF URL. It clearly distinguishes itself from sibling tools like get_analysis_study by specifying 'étude PPA terminée' (completed study) and by mentioning the report content.

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 a clear usage context: use it for a completed PPA study when you have the secret receipt. It does not explicitly name alternatives or exclusions, but the scope is well defined enough for an agent to know when this tool is appropriate.

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

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

Annotations already mark the operation as read-only and idempotent. The description adds useful behavioral context: the tool only exposes the study tied to the receipt, cannot list or open other studies, and returns structured results only when the study reaches readiness, disclosing the status set (queued/running/complete/partial/failed). No contradiction with 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?

The description is two front-loaded sentences with no redundant words. The first sentence states the core action; the second adds the result and the access limitation, both essential.

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 single-parameter polling tool: it explains the statuses, the result condition, the access restriction, and an output schema exists to define return values. It could tie back to create_analysis_study as the source of the receipt, but this is strongly implied by the sibling context.

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 0% schema description coverage, the description compensates by explaining that the receipt is secret and is the sole access key to a specific temporary study. It does not specify how the receipt is obtained or its format details, but the schema pattern (^bas_[A-Za-z0-9_-]{43}$) covers format; the description supplies the semantic role.

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 reads the queued/running/complete/partial/failed status of a temporary study from its secret receipt, and returns a structured result when ready. It also explicitly excludes listing or opening another study, which differentiates it from sibling tools like get_analysis_report or create_analysis_study.

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 establishes clear context: this is a polling/status-check tool for a temporary study accessed via a secret receipt, and it returns the result only when ready. It does not name an alternative tool or state when not to use it, leaving the selection vs siblings (e.g., get_analysis_report) 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?

The description adds meaningful behavior beyond the annotations: it explains that omitting all filters returns the entire registry, that filtering is the way to limit payload size, and what content the response will contain. This is consistent with the read-only, idempotent, non-destructive 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?

The description is a single well-structured sentence with no fluff: it states the return value first, then the filter options, then the default behavior. Every clause 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?

For a simple read-only retrieval tool with an output schema and annotations already provided, the description is complete: it tells the agent what it returns, what the parameters are for, and what happens without filters. No critical selection or invocation information 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?

Although the schema has 0% description coverage, the description names all three parameters (method_id, family, version) and explains their role as filters. It could go further by describing value formats or filter combination behavior, but it compensates for the bare schema meaningfully.

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 clearly states a specific verb ('Retourne') and resource: the calculation methodology including its sources, hypotheses, and limitations. It is easy to distinguish from sibling tools like get_analysis_report or get_analysis_study because it specifically targets methodology metadata rather than analysis results.

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 practical guidance on how to use the tool: filter by method_id, family, or version to avoid loading the full registry, and explains the no-filter default behavior. It does not explicitly mention alternative tools or when not to use it, but the intended usage context is well established.

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

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

Annotations already declare this a read-only, idempotent, non-destructive computation, so the safety profile is covered. The description adds real behavioral context beyond them: it bills the same consumption twice with identical prices and subscription, prices must be TTC and supplied by the caller, and 'rien n'est conservé' (stateless).

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 computation and the key negative constraint, then layers supporting detail. Every sentence carries information, though the density and slightly convoluted phrasing cost a point.

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 5-parameter tool with heavy nesting, the description supplies the essential mental model (double billing, caller-provided prices, no address resolution) and an output schema exists to cover return values. Only the omitted 'alternatives' parameter and window-structure semantics leave a 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 0%, so the description must compensate, and it only partly does: it explains that consumption can be a billed HP/HC split or annual figure and that schedules come from bill/mail. It says nothing about the optional 'alternatives' parameter, the winter/summer window structure, or the 'evidence' enum.

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 (calcule) and resource (impact d'un changement de plages d'heures creuses), and adds a scoping constraint ('deux horaires explicitement fournis, sans résoudre un horaire depuis une ville') that separates it from schedule-resolution tools. It does not name any of the sibling tools, so differentiation from simulate/run_method 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?

Gives clear applicability: two schedules must be supplied by the caller (from courrier or facture), consumption may be a billed HP/HC split or an annual figure, and the measured curve comes from the Boncourant study. It effectively states a when-not (no address resolves HC hours) but names no 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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by revealing that it acts as a router/oracle returning not just capability names but also required evidence, deliverables, limits, methods, and next MCP tools to call—useful context beyond the annotations.

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

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

Two concise, front-loaded sentences: the first enumerates what will be returned, and the second gives the routing condition. Every part is useful and there is 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 low-complexity discovery tool with an output schema, the description adequately covers when to invoke it and what categories of information to expect. It would be stronger if it also clarified the 'audience' parameter, but the missing information is not critical enough to severely hamper a correct call.

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 50%: the 'audience' parameter has an enum but no explanation of what each value means, and 'capability_id' only has a terse reference to a previous call. The description itself does not explain either parameter, so the agent gains little semantic understanding beyond the raw 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?

The description names a specific verb ('Liste') and concrete resource categories: available analyses, required evidence, deliverables, limits, methods, and next MCP tools to call. It also positions the tool as the first-step router for French electricity queries, clearly distinguishing it from the analytical siblings.

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 states when to use the tool: first, whenever the request concerns electricity in France or when the right path is uncertain. It does not list when-not-to-use conditions or specific alternative tools, but the routing instruction provides clear contextual guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so the safety profile is covered. The description adds real behavioural context beyond that: the data source (comparateur du Médiateur national de l'énergie), weekly refresh cadence, and the significant asymmetry that C4 returns only a supplier count because C4 pricing is quote-only.

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 verb and the core scope, and every clause carries information — segment limits, returned facets, the C4 exception, and the provenance/cadence. The first sentence is very dense (a colon-delimited enumeration spanning both segments before the C4 caveat), which costs a little readability but no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters, a full read-only annotation set and an output schema present, the description covers everything the agent needs: what the tool is, which segment it serves, what happens for the other segment, and how fresh/sourced the data is. Nothing relevant is missing 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description does not need to explain argument semantics, and the segment behaviour it describes (C5 vs C4) is output-side, not argument-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 definition names a specific verb ("Lit le catalogue vérifié") plus the exact resource domain (offres d'électricité professionnelles, segment C5 jusqu'à 36 kVA) and enumerates the returned facets: active offer count, suppliers, published all-in price spread, fixed/indexed split, last weekly reading date. This scope is unmistakably distinct from every sibling (analyze_bill, simulate, assess_ppa, etc.), so an agent can route to it 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 only implied: the tool answers 'what does the professional offer market look like for C5' and explicitly scopes itself to that segment, including the C4 behaviour. There is no statement of when to prefer this over siblings such as simulate or analyze_renewal_terms, and no prerequisites or exclusions.

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 useful behavioral rules beyond that: a stale or partial curve never triggers a decision, and only HT supply prices are compared against the locked HT supply price. These are real decision-guardrails that an agent could not infer from the schema or 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?

The purpose and routing are front-loaded in a single dense sentence, with no filler or repetition. It is information-packed but readable; the semicolon-chained clauses are justified by the amount of routing and guardrail information conveyed.

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?

An output schema exists, so return values need not be described, and the sibling routing and decision guardrails are present. However, for a 12-parameter tool with 8% schema coverage and a complex pricing domain, the near-total absence of parameter semantics leaves the definition short of what an agent needs to populate the inputs 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 only 8% across 12 parameters, so the description carries the burden and largely fails to. It hints at a few inputs (préavis, courbe EEX, prix verrouillé HT fourniture, segment C5/C4) but leaves structure, auto_renewal, pricing_type, budget_eur_mwh, ceiling_eur_mwh, evaluation_date, locked_fraction and annual_consumption_mwh undocumented in both schema and prose.

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 gives a specific verb+resource ('Conseille un renouvellement B2B') and, more importantly, explains the composition of the advice (notice period + fresh EEX curve via eex_connector + C5 catalog via pro_catalog). It explicitly differentiates from the sibling analyze_renewal_terms and notes that C4 prices are excluded. The only weakness is that the core action verb remains somewhat generic, but the routing context makes it distinct from siblings.

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 names the alternative (analyze_renewal_terms) and the precise condition that selects it: 'pour les seules dates contractuelles sans marché'. It also sets an exclusion boundary ('Les prix C4 restent sur devis'), telling the agent this tool won't price C4. It stops short of stating when NOT to use renewal_advisor itself, so it is clear context rather than a full when/when-not matrix.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the safety profile is known. The description adds useful operational behavior beyond annotations: it executes pure methods directly and explicitly rejects non-serializable contexts. No contradiction with 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?

Two short, front-loaded sentences with no filler. The core action and the main exclusion are stated immediately, so every sentence 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?

Because an output schema and rich annotations exist, return values and safety are covered elsewhere. The description still leaves valid_on vs version and the precise meaning of 'hash d'entrée' implicit, but the reference to get_methodology and the serializability rule give enough orientation for most callers.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it only mentions 'version' and an input hash that is not an actual schema property. It does not explain method_id, input, valid_on, or context, leaving the agent without parameter-level guidance beyond schema names and constraints.

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 ('Exécute directement') and resource ('méthode pure publiée par get_methodology'), and adds key selection details: version, JSON Schema, input hash, and explicit refusal of non-serializable contexts. This clearly differentiates it from get_methodology: get publishes, run executes.

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

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

It gives a clear when-not: methods requiring non-serializable context such as the Tempo calendar are explicitly refused. It also implies that only methods published by get_methodology are eligible. However, it does not name alternatives or explicitly say when to prefer siblings like simulate.

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 closed-world, so the safety profile is covered. The description adds behavioral context beyond annotations: it compares evaluated offers against the regulated tariff and surfaces its assumptions. It stops short of describing estimation accuracy or error behavior, so not quite 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?

Two front-loaded clauses with no filler, and the routing information comes immediately after the purpose. The semicolon-joined structure is dense but each clause 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?

With an output schema present, return values need no explanation, and the description covers the routing decision and the estimation basis. The only minor gap is that it doesn't state default behavior when option is omitted, which the agent must infer.

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

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

Schema description coverage is 80%, so the schema already documents postal_code, proportion_hc, puissance_kva and conso_annuelle_kwh, including the HP/HC conditionality. The description lists inputs but adds no format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

Names a specific function (fast residential estimation) plus the exact inputs (kWh, kVA, postal code, option) and the outcome (offer comparison at the regulated tariff). It explicitly distinguishes itself from the sibling analyze_bill, so an agent can route 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 an explicit when-to-use/when-not rule: use this when no bill has been extracted, and use analyze_bill when structured bill fields are available. The alternative and the selecting condition are both named.

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