Boncourant

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, lowering the bar; the description still adds meaningful context beyond them: the versioned engine, the explicit stay/switch and per-offer tariff output, and a specific edge-case guarantee that recommended_offer never points to a pricier catalog offer when nothing beats the current contract. The JSON-only note is an actionable transport constraint.

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 with no filler: purpose is front-loaded, then output behavior, then the usage constraint. Every sentence earns its place relative to the 9-parameter schema and the output schema.

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 analysis tool with a full output schema and 100% parameter coverage, the description covers purpose, output behavior, and the required upstream extraction step. The only gap is explicit routing among the many sibling analysis tools (analyze_renewal_terms, simulate, assess_*), but that is not essential to making 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 100% — every parameter already has a meaningful description, so the baseline is 3. The tool description only refers generically to 'les champs' and adds no parameter-specific meaning beyond what the schema already provides.

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

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

The description states a precise verb+resource: analyzing an already-extracted residential electricity bill via the versioned engine. The qualifier 'déjà extraite' plus the explicit stay/switch verdict separates it from extraction siblings (extract_energy_document) and simulation/analysis 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?

The description gives a clear workflow precondition: extract the PDF first, then call with structured fields, and warns that MCP is JSON only. This tells the agent where in the pipeline to invoke the tool, though it does not explicitly name alternative sibling tools or state when-not-to-use conditions.

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. The description adds useful behavioral context by specifying that the tool consumes already-extracted clauses and treats pricing_type as a canonical value rather than inferring it. Return/error behavior is left to the output schema, which is acceptable.

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 focused sentences, front-loaded with the main action and outputs. It contains no filler and each sentence adds necessary 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 read-only/idempotent annotations and an output schema present, the description provides the core contract: inputs must be already-extracted clauses, pricing is canonical, and the outputs are explicitly listed. The main gap is parameter-level detail, but the schema's clear names and enum make the tool adequately callable.

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%, and the description only clarifies pricing_type ('valeur canonique, jamais déduit d'un texte libre'). It does not explain evaluation_date, end_date, auto_renewal, or notice_period_days, forcing the agent to rely on parameter names 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?

The description states a specific verb and resource: it calculates maturity, notice deadline, overrun, and urgency from already-extracted clauses. The phrase 'clauses déjà extraites' differentiates it from extraction-focused siblings like extract_energy_document.

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 implies when to use it: after clauses have already been extracted. It also explicitly states an exclusion: pricing type is a canonical value and is never deduced from free text. It does not name alternative sibling tools, so it stops short of a full routing explanation.

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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavioral detail: it reads the most recent public snapshot and explicitly indicates when no recent data is available. This informs the agent about data freshness handling.

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, tight sentence that front-loads the essential data (market, contracts, source) and adds the no-data behavior without filler. Every phrase 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, safe annotations, and one clearly documented optional parameter, the description fully covers source, content, and availability behavior. Nothing critical is missing for an agent to invoke the tool correctly.

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

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

The schema already documents the single optional parameter 'asof' with ISO format and default value, so schema coverage is 100%. The description adds no additional parameter-level meaning, which matches the baseline of 3 for high schema coverage.

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 ('Lit') and resource ('Courbe forward EEX France' with defined contracts CAL Y+1, CAL Y+2, M+1). It clearly distinguishes itself from the sibling tools, which all concern invoices, PPAs, or analyses rather than market data.

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 context: this tool retrieves the latest EEX forward curve from market_observation. Although it does not explicitly name alternatives or exclusion conditions, no sibling tool provides similar market data, so the intended use case is obvious and 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?

The annotations already signal read-only, idempotent, and non-destructive behavior. The description adds important non-obvious behavioral details: the document is not persisted, sensitive identifiers are removed from the response, deterministic methods are launched immediately, and uncertain fields require confirmation. No contradiction with the annotations 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?

Two dense sentences carry the full description, with the primary action front-loaded and no filler. Each clause contributes meaningful behavioral or lifecycle 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?

Given the tool's complexity, the available output schema, and rich annotations, the description covers the essential workflow, data-handling caveats, and uncertainty behavior. It is slightly incomplete in routing the agent away from sibling audit/analysis tools and leaving segment and evaluation_date semantics to the schema, but it is adequate for selecting and invoking the 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 only 33%, and the description partially compensates by clarifying that input can be a PDF or already-extracted text and that the document kind is bill/contract. However, it does not explain segment, evaluation_date, or how document_file and document_base64 should be selected, so the compensation is incomplete.

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 extracts PDF/text of a bill/contract via the European extractor and then removes sensitive identifiers and launches deterministic methods. This is clear and distinct from a vague restatement, but it does not explicitly differentiate itself from sibling tools such as analyze_bill or decompose_invoice.

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 a clear usage context: call this tool when a bill/contract document needs to be loaded into memory, sanitized, and immediately processed by applicable deterministic methods. However, it does not state when not to use it or point to alternative sibling tools, so routing guidance remains implicit 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?

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 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 the tool read-only, idempotent, and non-destructive, so the description appropriately adds value beyond them by disclosing that data is collected weekly from the Médiateur national de l'énergie comparator, including the date of the last weekly reading. It also discloses the C4 limitation transparently. This is solid behavioral context without contradicting 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 compact and efficiently structured: the first sentence front-loads the main catalog contents for C5, and the second sentence handles the C4 exception. Every clause adds distinct information, with no filler or 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 no parameters, rich annotations, and an existing output schema, the description covers the essential context: what data is available, for which segments, how current it is, and where it originates. The C4 limitation is explicitly disclosed, so an agent has enough context to invoke the tool correctly and interpret its results.

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 has zero parameters and the schema is empty with 100% coverage, so there is nothing for the description to explain about inputs. The description instead compensates by enumerating the output aspects, which is appropriate for a parameterless catalog tool. The baseline of 4 for zero parameters is warranted.

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 identifies the tool as a verified catalog of professional electricity offers, specifying the C5 segment and the exact data points returned (number of active offers, suppliers, price range, fixed/indexed split, date of last weekly update). It also explicitly differentiates the C4 segment behavior, making the tool's scope unmistakable and distinguishing it from the analysis-oriented 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 on what the tool returns for each segment, including the important limitation that C4 prices are only available on quote. However, it does not explicitly state when to choose this tool over sibling tools or mention alternatives by name, so it stops short of full usage direction.

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 read-only and idempotent annotations, the description discloses two important behaviors: a stale or partial EEX curve never triggers a decision, and only supply prices excluding tax are compared to the locked supply price excluding tax. This adds valuable operational constraints that an agent cannot infer from the 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?

The description is only two sentences, front-loads the core inputs, and ends with the key comparison and safety rule. Every sentence contributes essential information with 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?

The description provides the essential decision rule and data-source constraints, and an output schema exists to describe return values. However, with 12 parameters and very low schema description coverage, many parameters and their role in the renewal decision remain to be inferred by the agent. It is adequate but has clear completeness gaps.

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%, so the description carries a heavy burden. It explains some inputs indirectly, such as échéance and préavis for end_date and notice_period_days, and the locked supply price comparison for current_locked_supply_eur_mwh. But most parameters, including segment, structure, pricing_type, budget_eur_mwh, ceiling_eur_mwh, locked_fraction, and annual_consumption_mwh, remain semantically unexplained.

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 title states it advises on professional renewal, and the description gives a specific combination of inputs: contract end date, notice period, fresh EEX CAL Y+1/Y+2 curve, and comparable professional catalog. It is clearly a renewal advisory tool, though it does not explicitly differentiate itself from siblings like analyze_renewal_terms.

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 the tool is used when contract terms, a fresh market curve, and a comparable catalog are available, and when a renewal decision is needed. However, it gives no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as analyze_renewal_terms or assess_ppa.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it computes an annual bill, compares market offers to the regulated tariff, and estimates savings. It does not detail data sources or assumptions, but for a read-only simulation this is solid transparency.

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 with no filler, the main action is front-loaded, and the comparative/savings purpose follows naturally. Every clause earns its place and the description is easy for an agent to scan.

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 a high-coverage schema, clear annotations, and an output schema present, the description covers what the tool does well enough for invocation. The main gap is explicit sibling routing, captured in usage_guidelines, and minor lack of caveats about market-offer data, but nothing critical is missing for a read-only simulation 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 80%, so most parameters are already well-documented in the schema, including the conditional proportion_hc rule. The description itself adds no parameter-level explanation beyond the overall simulation and savings context. This matches the baseline expected when the schema carries most of the semantic weight.

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: 'Simule la facture annuelle d'électricité pour un foyer français.' The additional clause about comparing market offers to the regulated tariff and estimating savings clearly distinguishes it from bill-analysis or invoice-annualization siblings like analyze_bill, annualize_invoice, and renewal_advisor.

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 the use case—simulating a French residential annual electricity bill and comparing offers—but it never explicitly states when to prefer this tool over alternatives or when not to use it. Given the large sibling set, an agent gets no direct routing or exclusion guidance, only inferred context.

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